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