ascommand(3x)ascommand(3x)NAMEascommand - execute an array command
SYNOPSIS
#include <arraysvcs.h>
ascmdrsltlist_t *ascommand(asserver_t Server, ascmdreq_t *Command);
DESCRIPTION
The ascommand function is used to execute an array command. The command
request will be processed by an array services daemon. That array
services daemon is responsible for translating the array command into an
actual UNIX command, running it on one or more machines in the requested
array, and returning the results.
The Server argument specifies an optional array server token, which can
be used to direct the request to a specific array services daemon. If
NULL is specified instead, the request will be processed by the default
array services daemon (see array(1) for more information on how the
default array services daemon is selected). For more details on creating
an array server token, see asopenserver(3X).
The Command argument is a pointer to an ascmdreq_t structure (defined in
<arraysvcs.h>) that describes the command request. An ascmdreq_t looks
similar to this:
typedef struct ascmdreq {
char *array;
uint32_t flags;
int numargs;
char **args;
uint32_t ioflags;
} ascmdreq_t;
The array member specifies the name of the array on which the command
should be executed. If array is set to NULL, the server's default
destination will be used if one has been specified, otherwise the command
request will be rejected. flags is used to specify various control
options for the command. It if formed by OR-ing together zero or more of
the following values:
ASCMDREQ_LOCAL
Run the command on the server machine only, rather than
broadcasting it to the machines in an array. If this option is
specified, the array member of Command will be ignored.
ASCMDREQ_NEWSESS
Run the command in a new global array session. The array services
daemon will allocate a new global array session handle and ensure
that each machine executes the array command in an array session
using this handle.
Page 1
ascommand(3x)ascommand(3x)
ASCMDREQ_OUTPUT
Collect output from the array command. If specified, the stdout
and stderr of the array command will be saved on each machine. If
any output is in fact generated on a particular machine, the
ascmdrslt_t for that machine will contain a pathname to a
temporary file containing the output.
ASCMDREQ_NOWAIT
Ordinarily, the array services daemon will wait for the array
command to complete before returning the results. If this flag is
specified, the array services daemon will not wait. The
ascmdrslt_t for each machine will indicate that the command has
been initiated, but will not have a valid exit status for the
command.
ASCMDREQ_INTERACTIVE
Specifies that socket connections should be made to one or more of
the command's standard I/O file descriptors (stdin, stdout and/or
stderr). The exact connections to be made are specified in the
ioflags field of Command. If successful, the ascmdrslt_t for each
machine will contain socket descriptors for each of the requested
connections. If this flag is specified, then the ASCMDREQ_OUTPUT
flag is ignored and the ASCMDREQ_NOWAIT flag is implied (i.e. an
interactive request never waits for the command to complete).
The ioflags field of Command is examined only when the flags field has
the ASCMDREQ_INTERACTIVE flag set, and is used to indicate which of the
command's standard I/O descriptors should be routed back to the caller
via a socket connection. It is formed by OR-ing together one or more of
the following values:
ASCMDIO_STDIN
Requests a socket attached to the command's stdin.
ASCMDIO_STDOUT
Requests a socket attached to the command's stdout.
ASCMDIO_STDERR
Requests a socket attached to the command's stderr.
ASCMDIO_SIGNAL
Requests a socket that can be used to deliver signals to the
command (see below for details).
ASCMDIO_OUTERRSHR
Indicates that the command's stderr should be routed back over the
stdout channel. This flag is ignored if ASCMDIO_STDERR is not
also specified.
The numargs and args members of Command specify the array command itself
along with any arguments. They behave similarly to the argc and argv
arguments to a standard C program.
Page 2
ascommand(3x)ascommand(3x)
The results from each machine are summarized in ascmdrslt_t structures,
and a list of these structures, bundled together into an ascmdrsltlist_t
structure, is returned by ascommand.
Both ascmdrslt_t and ascmdrsltlist_t are defined in <arraysvcs.h>. The
storage for both structures is allocated using malloc(3) and can be
released using asfreecmdrsltlist(3X). An ascmdrslt_t structure looks
similar to this:
typedef struct ascmdrslt {
char *machine;
ash_t ash;
uint32_t flags;
aserror_t error;
int status;
char *outfile;
/* These fields only valid if ASCMDRSLT_INTERACTIVE set */
uint32_t ioflags;
int stdinfd;
int stdoutfd;
int stderrfd;
int signalfd;
} ascmdrslt_t;
The machine member contains the name of the machine that generated this
particular response. This is typically the network hostname of that
machine, although the system administrator can override that value with a
LOCAL HOSTNAME entry in the array services configuration file. The flags
member contains flags describing certain details about the command
results. It may contain zero or more of the following values OR-ed
together:
ASCMDRSLT_OUTPUT
Indicates that the command has generated output which has been
saved in a temporary file. The name of the temporary file can be
found in the outfile member.
ASCMDRSLT_MERGED
Indicates that although the array command may have been run on
more than one machine, the results were merged together by a MERGE
command on the array services daemon. This ascmdrslt_t describes
the results of the MERGE command only.
ASCMDRSLT_ASH
Indicates that the array command was run using a global array
session handle. The array session handle itself is saved in the
ash member of the ascmdrslt_t structure.
Page 3
ascommand(3x)ascommand(3x)
ASCMDRSLT_INTERACTIVE
Indicates that one or more connections have been established with
the standard I/O file descriptors of the running command. The
specific connections are described in the ioflags field of the
ascmdrslt_t structure.
The error member is a standard libarray error code that contains the
results of the command on the particular machine. For details on
libarray error codes, see aserrorcode(3X). If the "errno" subfield of
error is ASE_OK and the "what" field is ASOK_COMPLETED, then the status
member will contain the final exit status of the array command's process
on this machine.
The ioflags member contains flags that describe which connections have
been established with the running command. It is only valid if the
ASCMDRSLT_INTERACTIVE flag is set in the flags member. It will contain
one or more of the following values OR-ed together:
ASCMDIO_STDIN
A socket connection has been established with the command's stdin.
The socket descriptor is contained in the stdinfd member of the
ascmdrslt_t structure. Any data written to this descriptor will
be presented to the command's stdin.
ASCMDIO_STDOUT
A socket connection has been established with the command's
stdout. The socket descriptor is contained in the stdoutfd member
of the ascmdrslt_t structure. Any data that the command writes to
its stdout can be read from this descriptor.
ASCMDIO_STDERR
A socket connection has been established with the command's
stderr. The socket descriptor is contained in the stderrfd member
of the ascmdrslt_t structure. Any data that the command writes to
its stderr can be read from this descriptor.
ASCMDIO_SIGNAL
A socket connection that can be used to deliver signals to the
command has been established. The socket descriptor is contained
in the signalfd member of the ascmdrslt_t structure. Any signal
can be delivered to the running command by writing a single byte
containing the desired signal number to this descriptor.
Note that in some implementations, the same socket may be used to handle
both the stdin and stdout connections or both the stderr and signal
connections. Therefore, caution should be exercised before trying to
close only one socket in either of those pairs.
NOTESascommand is found in the library "libarray.so", and will be loaded if
the option "-larray" is used with cc(1) or ld(1).
Page 4
ascommand(3x)ascommand(3x)SEE ALSOarray(1), arrayd(1M), aserrorcode(3X), asfreecmdrsltlist(3X),
asopenserver(3X).
DIAGNOSTICSascommand returns a pointer to an ascmdrsltlist_t structure if
successful. If unsuccessful, ascommand returns NULL and sets aserrorcode
appropriately.
Page 5
