rexec_af Subroutine

Purpose

Allows command execution on a remote host.

Syntax

int rexec_af(char **ahost, unsigned short rport, const char *name,
                   const char *pass, const char *cmd, int *fd2p, int af)

Description

The rexec_af subroutine allows the calling process to start commands on a remote host. It behaves the same as the existing rexec() function, but instead of creating only an AF_INET TCP socket, it can also create an AF_INET6 TCP socket.

The rexec_af subroutine is useful because the existing rexec() function cannot transparently use AF_INET6 sockets. This is because an application would not be prepared to handle AF_INET6 addresses returned by functions such as getpeername() on the file descriptor created by rexec().

If the rexec_af connection succeeds, a socket in the Internet domain of type SOCK_STREAM is returned to the calling process and is given to the remote command as standard input and standard output.

All applications containing the rexec_af subroutine must be compiled with the _BSD macro set to a specific value. Acceptable values are 43 and 44. In addition, all socket applications must include the BSD libbsd.a library.

Parameters

Item Description
ahost Contains the name of a remote host that is listed in the /etc/hosts file or /etc/resolv.config file. If the name of the host is not found in either file, the rexec subroutine is unsuccessful.
rport Specifies the well-known DARPA Internet port to use for the connection. A pointer to the structure that contains the necessary port can be obtained by issuing the following library call: 
getservbyname("exec","tcp")
name and pass Points to a valid user ID and password at the host. If these parameters are not supplied, the rexec_af subroutine takes the following actions until it finds a user ID and password to send to the remote host:
  1. Searches the current environment for the user ID and password on the remote host.
  2. Searches the user's home directory for a file called $HOME/.netrc that contains a user ID and password.
  3. Prompts the user for a user ID and password.
cmd Points to the name of the command to be executed at the remote host.
fd2p Specifies one of the following values:
Non-zero
Indicates that an auxiliary channel to a control process is set up, and a descriptor for it is placed in the fd2p parameter. The control process provides diagnostic output from the remote command on this channel and also accepts bytes as signal numbers to be forwarded to the process group of the command. This diagnostic information does not include remote authorization failure, since this connection is set up after authorization has been verified.
0
Indicates that the standard error of the remote command is the same as standard output, and no provision is made for sending arbitrary signals to the remote process. In this case, however, it might be possible to send out-of-band data to the remote command.
af The family argument is AF_INET, AF_INET6, or AF_UNSPEC. When either AF_INET or AF_INET6 is specified, this subroutine will create a socket of the specified address family. When AF_UNSPEC is specified, it will try all possible address families until a connection can be established, and will return the associated socket of the connection.

Return Values

Upon successful completion, the system returns a socket to the remote command. If the rexec_af subroutine is unsuccessful, the system returns a –1, indicating that the specified host name does not exist.

Files

Item Description
/etc/hosts Contains host names and their addresses for hosts in a network. This file is used to resolve a host name into an Internet address.
/etc/resolv.conf Contains the name server and domain name.
$HOME/.netrc Contains automatic login information.