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.
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004