NAME
	  rcmd - Allows	execution of commands on a remote host

     LIBRARY
	  Standard C Library (libc.a)

     SYNOPSIS
	  int rcmd (
	       char **host,
	       u_short port,
	       char *local_user,
	       char *remote_user,
	       char *command,
	       int *err_file_desc );


     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()
		    function fails. The	function sets the host parame-
		    ter	to be the fully	qualified host name.

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

	  local_user
		    Points to user names that are valid	at the local
		    host.  Any valid user name can be given.

	  remote_user
		    Points to user names that are valid	at the remote
		    host.  Any valid user name can be given.

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

	  err_file_desc
		    Specifies an integer that controls the set up of
		    communications channels.  Integer options are as
		    follows:


		      o	 If a nonzero integer is specified, an auxili-
			 ary channel to	a control process is set up,
			 and the error_file_desc 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 com-
			 mand.

		      o	 If 0 (zero) is	specified, the standard	error
			 (stderr) of the remote	command	is the same as
			 the 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.


     DESCRIPTION
	  The rcmd() (remote command) function allows execution	of
	  certain commands on a	remote host that supports the rshd(),
	  rlogin(), and	rpc() functions, among others.

	  The rcmd() function looks up a host via the name server or,
	  if the local name server is not running, via the /etc/hosts
	  file.If the connection succeeds, a socket in the Internet
	  domain of type SOCK_STREAM is	returned to the	calling	pro-
	  cess and given to the	remote command as standard input
	  (stdin) and standard output (stdout).

	  Always specify the host name.	 If the	local domain and
	  remote domain	are the	same, specifying the domain parts is
	  optional.  The rcmd()	function returns the fully qualified
	  host name in the host	parameter. To reuse the	host name in
	  another rcmd() call, you should make a string	copy of	the
	  host parameter. For example:

	      rcmd ( &host, .... );
	      host = strdup(host);
	      ...
	      rcmd ( &host, .... );


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

     RETURN VALUES
	  Upon successful completion, the rcmd() function returns a
	  valid	socket descriptor.  The	function returns -1 if the
	  effective user ID of the calling process is not root user,
	  if the function fails	to resolve the host, or	if it
	  encounters a socket connection error.

     FILES
	  /etc/services
		    Contains the service names,	ports, and socket
		    types.

	  /etc/hosts
		    Contains hostnames and their addresses for hosts
		    in a network.

	  /etc/resolv.conf
		    Contains the name server and domain	name.


     RELATED INFORMATION
	  Functions: gethostname(2), rresvport(3), ruserok(3),
	  sethostname(2)

	  Commands: rlogind(8),	rshd(8), named(8)