ascommand(3x)
ascommand - execute an array command
As shipped in IRIX 6.5.7. Unchanged since IRIX 6.5.
NAME 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 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. 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. 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. 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. 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), asfreecmdrsltlist(3X), asopenserver(3X). DIAGNOSTICS ascommand returns a pointer to an ascmdrsltlist_t structure if successful. If unsuccessful, ascommand returns NULL and sets aserrorcode appropriately.