rcmd Subroutine

AIX Version 4.3 Communications Technical Reference, Volume 2

rcmd Subroutine

Purpose

Allows execution of commands on a remote host.

Library

Standard C Library (libc.a)

Syntax

int rcmd (Host, 
Port, LocalUser, RemoteUser, Command, ErrFileDesc)
char **Host;
u_short Port;
char *LocalUser;
char *RemoteUser;
char *Command;
int *ErrFileDesc;

Description

The rcmd subroutine allows execution of certain commands on a remote host that supports rshd, rlogin, and rpc among others.

Only processes with an effective user ID of root user can use the rcmd subroutine. An authentication scheme based on remote port numbers is used to verify permissions. Ports in the range between 0 and 1023 can only be used by a root user.

The rcmd subroutine looks up a host by way of the name server or if the local name server isn't running, in the /etc/hosts file.

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

Always specify the Host parameter. If the local domain and remote domain are the same, specifying the domain parts is optional.

Parameters

Host

Specifies the name of a remote host that is listed in the /etc/hosts file. If the specified name of the host is not found in this file, the rcmd subroutine is unsuccessful.

Port

Specifies the well-known port to use for the connection. The /etc/services file contains the DARPA Internet services, their ports, and socket types.

LocalUser and RemoteUser

Points to user names that are valid at the local and remote host, respectively. Any valid user name can be given.

Command

Specifies the name of the command to be started at the remote host.

ErrFileDesc

Specifies an integer controlling the set up of communication channels. Integer options are as follows:

Non-zero	Indicates an auxiliary channel to a control process is set up, and the ErrFileDesc parameter points to the file descriptor for the channel. 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.
0	Indicates the standard error (stderr) of the remote command is the same as standard output (stdout). No provision is made for sending arbitrary signals to the remote process. However, it is possible to send out-of-band data to the remote command.

Return Values

Upon successful completion, the rcmd subroutine returns a valid socket descriptor.

Upon unsuccessful completion, the rcmd subroutine returns a value of -1. The subroutine returns a -1, if the effective user ID of the calling process is not root user or if the subroutine is unsuccessful to resolve the host.

Implementation Specifics

The rcmd subroutine is part of Base Operating System (BOS) Runtime.

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

Files

/etc/services		Contains the service names, ports, and socket type.
/etc/hosts		Contains host names and their addresses for hosts in a network.
/etc/resolv.conf		Contains the name server and domain name.

Related Information

The rlogind command, rshd command.

The named daemon.

The gethostname subroutine, rresvport subroutine, ruserok subroutine, sethostname subroutine.

Sockets Overview in AIX Version 4.3 Communications Programming Concepts.