asrcmd(3x)

NAME
     asrcmd, asrcmdv - execute a command on a remote machine

SYNOPSIS
     #include <arraysvcs.h>

     int asrcmd(asserver_t Server, char *User, char *CmdLine, int *fd2p);
     int asrcmdv(asserver_t Server, char *User, char **CmdV, int *fd2p);

DESCRIPTION
     The asrcmd and asrcmdv functions are used to execute an arbitrary command
     on a remote machine.  They are similar in some respects to rcmd(3N)
     except that the connection and user authentication is provided by Array
     Services, so the user does not necessarily have to have root privileges.
     Both asrcmd and asrcmdv pass the command to the remote user's default
     shell for execution using the standard shell command line option "-c".
     For example, if the requested command is ls -l and the remote user's
     shell is /bin/tcsh, then the following command would be invoked on the
     remote machine:

          /bin/tcsh -c "ls -l"

     The only difference between asrcmd and asrcmdv is in the way that the
     remote command is specified.

     The Server argument is an array server token created with
     asopenserver(3X) that specifies the remote machine that is to execute the
     command.  If NULL is specified instead, the command will be executed on
     the same machine as the one running the default array services daemon,
     though this is not generally very useful.  See array(1) for more
     information on how the default array services daemon is selected.

     The User argument specifies the login name of the user on the remote
     machine that should execute the command.  Specifying NULL will cause the
     command to be executed using the same user login name as the one
     executing asrcmd/asrcmdv.

     The CmdLine argument to asrcmd is a single string containing the entire
     command to be executed, such as it might be typed on the command line.

     The CmdV argument to asrcmdv is an argv-style array of string pointers
     containing the list of arguments that make up the command to be executed.
     The array should be terminated with a NULL pointer.  Note that the list
     of arguments will be concatenated into a single string (with a single
     space between each) before it is passed to the remote user's default
     shell for execution.  It may therefore be necessary to include
     appropriate shell quote characters if individual arguments contain
     embedded space or tab characters.

     If the remote command is successfully initiated, a socket in the internet
     domain of type SOCK_STREAM is returned to the caller and given to the
     remote command as stdin and stdout.  If fd2p is non-zero, then an
     auxillary channel to a control process will be set up, and a descriptor
     for it will be placed in *fd2p.  The control process will return output
     from the command's stderr, and will also accept bytes on this channel as
     being UNIX signal numbers, to be forwarded to the process group of the
     command.  If fd2p is 0, then the stderr of the remote command will be
     made the same as the stdout and no provision is made for sending
     arbitrary signals to the remote process.

NOTES
     asrcmd and asrcmdv are 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), ascommand(3X), aserrorcode(3X), asopenserver(3X), rcmd(3N).

DIAGNOSTICS
     If successful, asrcmd and asrcmdv both return a socket descriptor
     attached to the remote command's stdin and stdout.  If the remote command
     cannot be started, -1 is returned and aserrorcode is set appropriately.