1.\" Copyright (c) 1983, 1991 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)rcmd.3 6.11 (Berkeley) 04/19/91 7.\" 8.Dd 9.Dt RCMD 3 10.Os BSD 4.2 11.Sh NAME 12.Nm rcmd , 13.Nm rresvport , 14.Nm ruserok 15.Nd routines for returning a stream to a remote command 16.Sh SYNOPSIS 17.Fd #include <unistd.h> 18.Ft int 19.Fn rcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" 20.Ft int 21.Fn rresvport "int *port" 22.Ft int 23.Fn ruserok "const char *rhost" "int superuser" "const char *ruser" "const char *luser" 24.Sh DESCRIPTION 25The 26.Fn rcmd 27function 28is used by the super-user to execute a command on 29a remote machine using an authentication scheme based 30on reserved port numbers. 31The 32.Fn rresvport 33function 34returns a descriptor to a socket 35with an address in the privileged port space. 36The 37.Fn ruserok 38function 39is used by servers 40to authenticate clients requesting service with 41.Fn rcmd . 42All three functions are present in the same file and are used 43by the 44.Xr rshd 8 45server (among others). 46.Pp 47The 48.Fn rcmd 49function 50looks up the host 51.Fa *ahost 52using 53.Xr gethostbyname 3 , 54returning \-1 if the host does not exist. 55Otherwise 56.Fa *ahost 57is set to the standard name of the host 58and a connection is established to a server 59residing at the well-known Internet port 60.Fa inport . 61.Pp 62If the connection succeeds, 63a socket in the Internet domain of type 64.Dv SOCK_STREAM 65is returned to the caller, and given to the remote 66command as 67.Em stdin 68and 69.Em stdout . 70If 71.Fa fd2p 72is non-zero, then an auxiliary channel to a control 73process will be set up, and a descriptor for it will be placed 74in 75.Fa *fd2p . 76The control process will return diagnostic 77output from the command (unit 2) on this channel, and will also 78accept bytes on this channel as being 79.Tn UNIX 80signal numbers, to be 81forwarded to the process group of the command. 82If 83.Fa fd2p 84is 0, then the 85.Em stderr 86(unit 2 of the remote 87command) will be made the same as the 88.Em stdout 89and no 90provision is made for sending arbitrary signals to the remote process, 91although you may be able to get its attention by using out-of-band data. 92.Pp 93The protocol is described in detail in 94.Xr rshd 8 . 95.Pp 96The 97.Fn rresvport 98function is used to obtain a socket with a privileged 99address bound to it. This socket is suitable for use 100by 101.Fn rcmd 102and several other functions. Privileged Internet ports are those 103in the range 0 to 1023. Only the super-user 104is allowed to bind an address of this sort to a socket. 105.Pp 106The 107.Fn ruserok 108argument 109takes a remote host's name, as returned by the 110.Xr gethostbyaddr 3 111routine, two user names and a flag indicating whether 112the local user's name is that of the super-user. Then, 113if the user is 114.Em NOT 115the super-user, it checks the files 116.Pa /etc/hosts.equiv . 117If that lookup is not done, or is unsuccessful, the 118.Pa .rhosts 119in the local user's home directory is checked to see if the request for 120service is allowed. If this file is owned by anyone other than the 121user or the super-user, or if it is writeable by anyone other than the 122owner, the check automatically fails. A 0 is returned if the machine 123name is listed in the 124.Dq Pa hosts.equiv 125file, or the host and remote 126user name are found in the 127.Dq Pa .rhosts 128file; otherwise 129.Fn ruserok 130returns \-1. 131If the local domain (as obtained from 132.Xr gethostname 2 ) 133is the same as the remote domain, only the machine name need be specified. 134.Sh DIAGNOSTICS 135The 136.Fn rcmd 137function 138returns a valid socket descriptor on success. 139It returns \-1 on error and prints a diagnostic message on the standard error. 140.Pp 141The 142.Fn rresvport 143function 144returns a valid, bound socket descriptor on success. 145It returns \-1 on error with the global value 146.Va errno 147set according to the reason for failure. 148The error code 149.Dv EAGAIN 150is overloaded to mean ``All network ports in use.'' 151.Sh SEE ALSO 152.Xr rlogin 1 , 153.Xr rsh 1 , 154.Xr intro 2 , 155.Xr rexec 3 , 156.Xr rexecd 8 , 157.Xr rlogind 8 , 158.Xr rshd 8 159.Sh HISTORY 160These 161functions appeared in 162.Bx 4.2 . 163