HP-UX Reference (11i v1 00/12) - 3 Library Functions N-Z (vol 7)

ManualsBrandsHP ManualsSoftwareHP-UX Reference Manuals

251

252

253

254

255

256

257

258

259

260

__________________________________________________________________________________________________________________________________________________________________________________________________

STANDARD Printed by: Nora Chuang [nchuang] STANDARD

/build/1111/BRICK/man3/nan.3m

________________________________________________________________

___ ___

rcmd(3N) rcmd(3N)

NAME

rcmd(), rresvport(), ruserok() - return a stream to a remote command

SYNOPSIS

int rcmd(

char **ahost,

int remport,

const char *locuser,

const char *remuser,

const char *cmd,

int *fd2p);

int rresvport(int *port);

int ruserok(

const char *rhost,

int superuser,

const char *ruser,

const char *luser);

DESCRIPTION

rcmd()

The rcmd() function is used by privileged programs to execute a command on a remote host. rcmd()

returns a ﬁle descriptor for the socket to which the standard input and standard output of the command

are attached. A command level interface to rcmd() is provided by remsh (see remsh(1)), which is the

same as the BSD

rsh command.

ahost is a pointer to the address of the remote host name. The name of the remote host can be either an

ofﬁcial host name or an alias as understood by gethostbyname()

(see gethostent(3N), named(1M), and

hosts(4)).

remport is the Internet port on the remote system, which

rcmd() will try to connect to.

locuser and remuser point to the user login name on the local host and on the remote host, respectively.

The names are used by the server on the remote host to authenticate the user (see ruserok() below).

cmd points to a string that speciﬁes the command to be executed on the remote host.

fd2p is a pointer to an integer (it can be a NULL pointer).

rcmd() looks up the host *ahost using gethostbyname()

, returning −1 if the host does not exist.

Otherwise,

*ahost is set to the standard name of the host and a connection is established to a server

accepting requests at the port remport. If the connection is refused after ﬁve tries, or if it was refused for a

reason other than the port being in use, rcmd() returns −1.

If the call succeeds, a socket of type SOCK_STREAM is returned to the caller and given to the remote com-

mand as stdin and stdout.Iffd2p is non-NULL, rcmd() opens a second socket between the calling

process (local) and the control process (remote), and places its descriptor in *fd2p. On this connection, the

control process sends the diagnostic output (stderr) from cmd to the calling process, and receives UNIX

signals from the calling process, to be forwarded to cmd. If the auxiliary port cannot be set up, rcmd()

returns −1. If fd2p is NULL, stderr of the remote command is made the same as

stdout, and no provi-

sion is made for sending arbitrary signalsto the remote process.

The protocol is described in detail in remshd(1M).

Any program using

rcmd() must be run as superuser.

rresvport()

The rresvport() function creates a socket and binds it to a reserved port. This socket is suitable for

use by rcmd() and several other routines.

The caller is expected to set the initial value of *port to a number between 512 and

IPPORT_RESERVED−1. (The value of IPPORT_RESERVED

is deﬁned in netinet/in.h and is 1024.)

Typically, the initial value of

*port is set to IPPORT_RESERVED−1. If the value is outside the valid

range,

rresvport() resets it silently to IPPORT_RESERVED−1. The function uses the inital value of

*port as the ﬁrst port number that it tries to bind to the created socket. If the operation fails,

rresvport() decrements *port and attempts to bind the new port number to the socket. The process is

repeated until either the operation succeeds, or the port numbers between 512 and

HP-UX Release 11i: December 2000 − 1 − Section 3−−745

___