rexec()--Issue a Command on a Remote Host

Syntax

 #include <arpa/rexec.h>

 int rexec(char **host,
           int port,
           char *user,
           char *password,
           char *command,
           int *errorDescriptor);

  Service Program Name: QSOSRV2

  Default Public Authority: *USE

  Threadsafe: Yes

The rexec() function is used to open a connection to a remote host and send a user ID, password, and command to the remote host. The remote host verifies that the user ID and password are valid. The command is issued after the user ID and password are validated.

Parameters

host (Input)

A pointer to a character string that identifies the name of a remote host.

port (Input)

The well-known Internet port to use for the connection. A pointer to the structure containing the necessary port can be obtained by issuing the following call:

   getservbyname("exec", "tcp");

The port returned by getservbyname() is the port on which the remote host is listening for incoming rexec() connections.

user (Input)

A character string that identifies a valid user on the remote host.

password (Input)

A character string that identifies the password for the user on the remote host. Specify a value of NULL if password security is not active on the remote host.

command (Input)

A character string that identifies the command to be issued on the remote host.

errorDescriptor (Input/Output)

One of the following values:

non-NULL	A second connection is set up and that a descriptor for it is placed in the errorDescriptor parameter. This connection provides standard error results of the remote command. This information also includes remote authorization failure if rexec() is unsuccessful.
NULL	The standard error results of the remote command are the same as the standard output return value.

Return Value

rexec() returns an integer. Possible values are:

Non-negative

(successful) A socket to the remote command is returned and can be used to receive results of running the command on the remote host.

If errorDescriptor is non-NULL, standard error results of running the command on the remote host can be received by using the errorDescriptor.
If errorDescriptor is NULL, standard error results of running the command on the remote host can be received with the standard output results by using the return value from rexec().

[-1]

(unsuccessful) Refer to errno for a description of the failure.

If errno is 0 and errorDescriptor is NULL, the host does not exist or remote authorization failed.
If errno is 0 and errorDescriptor is -1, the host does not exist.
If errno is 0 and errorDescriptor is non-negative, remote authorization failed.

Authorities

No authorization is required.

Error Conditions

When the rexec() API fails, errno can be set to one of following:

[ECONNABORTED]	Connection ended abnormally.
[ECONNREFUSED]	The destination socket refused an attempted connect operation. This error occurs when the rexec server on the remote system is not active.
[ECONNRESET]	A connection with a remote socket was reset by that socket.
[EFAULT]	Bad address. System detected an address which was not valid while attempting to access the address parameters.
[EHOSTUNREACH]	A route to the remote host is not available.
[EINTR]	Interrupted function call.
[EINVAL]	Parameter not valid.
[EMFILE]	Too many descriptors for this process.
[ENFILE]	Too many descriptors in system.
[EPIPE]	Broken pipe.
[ETIMEDOUT]	A remote host did not respond within the timeout period. This error code is returned when connection establishment times out. No connection is established. A possible cause may be that the partner application is bound, but the partner application has not yet issued a listen().
[EUNATCH]	The protocol required to support address family AF_INET, is not available at this time.
[EUNKNOWN]	Unknown system state.

Usage Notes

The password does not get encrypted while sent to the rexec server.
Any results of the command received by the caller of rexec() are not converted from CCSID 819. Conversion from ASCII ccsid 819 to the CCSID of the process or thread is the caller's responsibility.
If a remote authorization failure occurs, the return value will be -1 and if errorDescriptor is non-null a message indicating the authorization failure can be received with the socket descriptor from errorDescriptor.
Any socket descriptor returned to the caller of rexec() must be explicitly closed by the caller.
The user, password, and command will be translated from the job ccsid to ASCII ccsid 819 to be sent to the remote host.
Issuing rexec() to a remote host that is configured to set up a SOCKSified connection is not supported.

Related Information

rexec_r()--Issue a Command on a Remote Host

Example

See Code disclaimer information for information pertaining to code examples.

The following example shows how rexec() is used:

#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <qtqiconv.h>
#include <arpa/rexec.h>
#include <errno.h>

#define BufLen 256

void main()
{
  int sd = -1, rc;
  int responseLen = BufLen;
  int outbytesleft = BufLen;
  int bytesRead, saveBytesRead;
  struct servent serv_ent;
  struct servent_data serv_ent_data;
  char inbuf[BufLen];
  char outbuf[BufLen];
  char *inbufPtr = (char *)inbuf;
  char *outbufPtr = (char *)outbuf;
  iconv_t cd;
  QtqCode_T toCode   = {0,0,0,0,0,0};    /* Convert to job CCSID */
  QtqCode_T fromCode = {819,0,0,1,0,0};  /* ASCII CCSID */
  char *host;
  char remoteHost[256] = "remoteHost";
  char user[32] = "userName";
  char password[32] = "myPassword";
  char cmd[256] = "commandToRun";
  int *errordesc = NULL;

  /* Must zero this out before call or results will be unpredictable. */
  memset(&serv_ent_data.serve_control_blk, 0x00, sizeof(struct netdb_control_block));

  /* retrieve the rexec server port number */
  rc = getservbyname_r("exec", "tcp", &serv_ent, &serv_ent_data);
  if (rc < 0)
    printf("getservbyname_r() failed with errno = %d\n",errno);

  host = remoteHost;
  errno = 0;

  /* Issue the rexec API */
  sd = rexec(&host, serv_ent.s_port, user, password, cmd, errordesc);
  if (sd == -1) /* check if rexec() failed */
  {
    if (errno)
      printf("rexec() failed with errno = %d\n",errno);
    else
      printf("Either the host does not exist or remote authentication failed.\n");
  }
  else /* rexec() was successful */
  {
    bytesRead = recv(sd, inbuf, responseLen, 0);
    if (bytesRead > 0)
    {
      saveBytesRead = bytesRead;
      inbuf[bytesRead-1] = 0;  /* Null terminate */
      /* translate from ASCII to EBCDIC */
      cd = QtqIconvOpen(&toCode, &fromCode);
      iconv(cd,
            (unsigned char **)&inbufPtr,
            (unsigned int *)&bytesRead,
            (unsigned char **)&outbufPtr,
            (unsigned int *)&outbytesleft);
      iconv_close(cd);
      outbufPtr -= saveBytesRead;  /* Reset the buffer pointers */
      printf("%s\n",outbufPtr);
    }
    else if (bytesRead == 0)
      printf("The remote host closed the connection.\n");
    else
      printf("recv() failed with errno = %d\n",errno);
  }
  if (sd != -1)
    close(sd);  /* close the connection. */
  return;
}

API introduced: V5R1

Top | UNIX-Type APIs | APIs by category