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

 #include <arpa/rexec.h>

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

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:

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

The following example shows how rexec() is used.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#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;
}

[ Back to top | UNIX-Type APIs | APIs by category ]