ascommand - 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 com
mand. The command request will be processed by an array
services daemon. That array services daemon is responsi
ble 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 spe
cific 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 struc
ture (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:
AASSCCMMDDRREEQQ_LLOOCCAALL
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.
AASSCCMMDDRREEQQ_NNEEWWSSEESSSS
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
session using this handle.
AASSCCMMDDRREEQQ_OOUUTTPPUUTT
Collect output from the array command. If speci
fied, 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 path
name to a temporary file containing the output.
AASSCCMMDDRREEQQ_NNOOWWAAIITT
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.
AASSCCMMDDRREEQQ_IINNTTEERRAACCTTIIVVEE
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_OUT
PUT 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:
AASSCCMMDDIIOO_SSTTDDIINN
Requests a socket attached to the command's stdin.
AASSCCMMDDIIOO_SSTTDDOOUUTT
Requests a socket attached to the command's std
out.
AASSCCMMDDIIOO_SSTTDDEERRRR
Requests a socket attached to the command's
stderr.
AASSCCMMDDIIOO_SSIIGGNNAALL
Requests a socket that can be used to deliver
AASSCCMMDDIIOO_OOUUTTEERRRRSSHHRR
Indicates that the command's stderr should be
routed back over the stdout channel. This flag is
ignored if AASSCCMMDDIIOO_SSTTDDEERRRR is not also specified.
The numargs and args members of Command specify the array
command itself along with any arguments. They behave sim
ilarly to the argc and argv arguments to a standard C pro
gram.
The results from each machine are summarized in ascm
drslt_t structures, and a list of these structures, bun
dled 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 allo
cated using malloc(3) and can be released using asfreecm
drsltlist(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_INTERAC
TIVE 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 HOST
NAME 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:
AASSCCMMDDRRSSLLTT_OOUUTTPPUUTT
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.
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.
AASSCCMMDDRRSSLLTT_AASSHH
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.
AASSCCMMDDRRSSLLTT_IINNTTEERRAACCTTIIVVEE
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 ascm
drslt_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 aser
rorcode(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 con
nections 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:
AASSCCMMDDIIOO_SSTTDDIINN
A socket connection has been established with the
command's stdin. The socket descriptor is con
tained in the stdinfd member of the ascmdrslt_t
structure. Any data written to this descriptor
will be presented to the command's stdin.
AASSCCMMDDIIOO_SSTTDDOOUUTT
A socket connection has been established with the
command's stdout. The socket descriptor is con
tained in the stdoutfd member of the ascmdrslt_t
structure. Any data that the command writes to
its stdout can be read from this descriptor.
AASSCCMMDDIIOO_SSTTDDEERRRR
A socket connection has been established with the
command's stderr. The socket descriptor is con
tained in the stderrfd member of the ascmdrslt_t
structure. Any data that the command writes to
AASSCCMMDDIIOO_SSIIGGNNAALL
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, cau
tion should be exercised before trying to close only one
socket in either of those pairs.
NOTES
ascommand is found in the library "libarray.so", and will
be loaded if the option "-larray" is used with cc(1) or
ld(1).
SEE ALSO
array(1), arrayd(1M), aserrorcode(3X), asfreecm
drsltlist(3X), asopenserver(3X).
DIAGNOSTICS
ascommand returns a pointer to an ascmdrsltlist_t struc
ture if successful. If unsuccessful, ascommand returns
NULL and sets aserrorcode appropriately.
Man(1) output converted with
man2html