rexec(3SOCKET)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ATTRIBUTES | SEE ALSO | NOTES

NAME

rexec, rexec_af– return stream to a remote command

SYNOPSIS

cc [ flag ... ] file ... -lsocket -lnsl [ library ... ]

int rexec(char **ahost, unsigned short inport, const char *user, const char *passwd, const char *cmd, int *fd2p);
int rexec_af(char **ahost, unsigned short inport, const char *user, const char *passwd, const char *cmd, int *fd2p, int af);

DESCRIPTION

rexec() and rexec_af() look up the host ahost using getipnodebyname(3SOCKET), returning -1 if the host does not exist. Otherwise ahost is set to the standard name of the host. If a username and password are both specified, then these are used to authenticate to the foreign host; otherwise the user's .netrc file in his home directory is searched for appropriate information. If all this fails, the user is prompted for the information.

The difference between rexec() and rexec_af() is that while rexec() always returns a socket of the AF_INET address family, with rexec_af() the application can choose which type of address family the socket returned should be. rexec_af() supports both AF_INET and AF_INET6 address families.

The port inport specifies which well-known DARPA Internet port to use for the connection. The port number used must be in network byte order, as supplied by a call to htons(3XNET). The protocol for connection is described in detail in in.rexecd(1M).

If the call succeeds, a socket of type SOCK_STREAM is returned to the caller, and given to the remote command as its standard input and standard output. If fd2p is non-zero, then an auxiliary channel to a control process will be setup, and a file descriptor for it will be placed in *fd2p. The control process will return diagnostic output (file descriptor 2, the standard error) from the command on this channel, and will also accept bytes on this channel as signal numbers, to be forwarded to the process group of the command. If fd2p is 0, then the standard error (file descriptor 2 of the remote command) will be made the same as its standard output and no provision is made for sending arbitrary signals to the remote process, although you may be able to get its attention by using out-of-band data.

RETURN VALUES

If rexec() succeeds, a file descriptor number, which is a socket of type SOCK_STREAM and address family AF_INET is returned by the routine. *ahost is set to the standard name of the host, and if fd2p is not NULL, a file descriptor number is placed in *fd2p which represents the command's standard error stream.

If rexec_af() succeeds, the routine returns a filed descriptor number, which is a socket of type SOCK_STREAM and of address family type AF_INET or AF_INET6, as determined by the value of the af parameter that the caller passes in.

If either rexec() or rexec_af() fails, -1 is returned.

ATTRIBUTES

See attributes (5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	Unsafe

SEE ALSO

in.rexecd(1M), gethostbyname(3NSL), getipnodebyname(3SOCKET), getservbyname(3SOCKET), htons(3XNET), socket(3SOCKET), attributes(5)

NOTES

There is no way to specify options to the socket() call that rexec() or rexec_af() makes.

This interface is unsafe in multithreaded applications. Unsafe interfaces should be called only from the main thread.

SunOS 5.9  Last Revised 29 Oct 2003

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ATTRIBUTES | SEE ALSO | NOTES