rexecve(3N)

rexecve, rx_set_ioctl_hand, rx_set_write_hand, rx_fd, rx_proc_msg, rx_write, rx_signal, rx_act_exit, rx_free_conn -- REXEC support routines

Synopsis

cc [options] file -lnsl

#include <sys/types.h>
#include <rx.h>

int rexecve(char *host, char *rx_service, char *argv[],
	char *envp[], long flags);

int rx_set_ioctl_hand(int cnum, int (*ioctl_hand)(int, int, ...));

int rx_set_write_hand(int cnum, ssize_t (*write_hand)(int, const void*,
	size_t));

int rx_fd(int cnum);

int rx_proc_msg(int cnum, long *msg_type, long *ret_code);

int rx_write(int cnum, char *buf, long len);

int rx_signal(int cnum, int signum);

int rx_ack_exit(int cnum, char *ta_buf, long ta_len);

int rx_free_conn(int cnum);

Description

The REXEC support routines contain all the functions required by an REXEC client program, such as the functions needed by rexec(1bnu) to communicate with the rxserver program.

The rexecve function is used to establish a connection to rxserver. rexecve contacts rxserver on the remote host host and attempts to start executing a service rx_service with the arguments specified by argv and the environment specified by envp. Options may be specified using the flags parameter:

RXF_STNDINPIPE: Informs REXEC that only one end-of-file condition can occur on stdin. If stdin is associated with a terminal, additional data can be sent after an end-of-file, so this flag would not be used.
RXF_SEPERR: Instructs rxserver to set up a separate standard output and standard error channels for data written by the remote service so that it may be treated separately by the client.

Once a connection has been successfully established, other library functions may be used to communicate with the remote service. rexecve returns a connection number cnum which needs to be specified when using other rx_ functions to refer to this particular connection.

The rx_set_ioctl_hand function is used to set a handler function for incoming RX_IOCTL messages. By default, the handler function is ioctl. The handler may be changed while an REXEC connection is in progress.

The rx_set_write_hand function is used to set a handler function for incoming RX_DATA messages. By default, the handler function is write. The handler may be changed while an REXEC connection is in progress.

The rx_fd function returns the file descriptor of an open REXEC connection (useful when using poll).

The rx_proc_msg function is called by the client program when it gets a new data indication from poll for the file descriptor used by the REXEC connection. rx_proc_msg reads an REXEC message header and message, and performs the appropriate actions depending on the type of message (such as RX_DATA or RX_IOCTL). The msg_type argument is a pointer to a user-supplied variable, which upon the return of the call is set to the message type that was received. The following are possible message types, from rx.h:

   #define RX_INCOMPLETE    1    /* incomplete message */
   #define RX_PROTOCOL      2    /* protocol message (open, close etc) */
   #define RX_SERVICE_DEAD  3    /* service termination message */
   #define RX_TYPEAHEAD     4    /* typeahead message */
   #define RX_DATA          5    /* data message */
   #define RX_IOCTL         6    /* ioctl message */
   #define RX_EOF           7    /* 0-length message */

The ret_code argument is a pointer to a user-supplied variable, which upon the return of the call is set to the error value as returned from the server (from the same list as the values for Rx_errno).

The rx_write function is used by the client program to send data to the remote service. Any data sent by rx_write will be passed to the remote service process' file descriptor 0 (stdin).

The rx_signal function is used by the client program to send a signal to the remote service. Only four signals are supported: SIGHUP, SIGINT, SIGQUIT, and SIGPIPE.

The rx_ack_exit function always returns -1. It is kept in the library for compatibility and may be removed in a future release.

The rx_free_conn function is used by the client program to close an REXEC connection and to free any resources (mainly the file descriptor) used by it. An internal version of rx_free_conn is invoked automatically by rx_proc_msg when an RX_EOF message is received, or when rxserver drops the connection.

Return values

Upon successful completion, the routines return 0, otherwise they return -1 and set Rx_errno to one of the following:

RXE_OK: No error
RXE_2MANYRX: Too many open rexec connections
RXE_BADFLAGS: Bad options/flags specified
RXE_BADARGS: Too many arguments
RXE_BADENV: Bad environment specification
RXE_BADMACH: Unknown host
RXE_CONNPROB: Connection problem
RXE_NORXSERVER: Host is not running rxserver
RXE_BADVERSION: Unsupported version
RXE_NOSVC: No such service
RXE_NOTAUTH: Not authorized to execute service
RXE_NOPTS: No pseudo terminals available
RXE_PIPE: rxserver cannot make pipe for stderr
RXE_BADSTART: Error in starting server side
RXE_NOSPACE: Server side memory allocation problems
RXE_BADCNUM: Bad rexec connection number
RXE_AGAIN: write would cause process to block
RXE_BADSIG: Bad signal number
RXE_BADSTATE: Connection in wrong state to perform operation
RXE_TIRDWR: Could not push TIRDWR module at client
RXE_WRITE: write handler failure at client
RXE_IOCTL: ioctl handler failure at client
RXE_PROTOCOL: Protocol failure--unexpected message
RXE_NOERRMEM: Could not allocate memory for error variable
RXE_UNKNOWN: Unknown error code

References

rexec(1bnu), rxlist(1Mtcp), rxservice(1Mbnu), get_Rx_errno(3N), get_Rx_cserrno(3N)

Notices

If the remote process exits before it consumes all the data that the client application has sent, this data will be lost.