1 files changed, 118 insertions, 56 deletions

diff --git a/src/lib/libc/net/rcmd.3 b/src/lib/libc/net/rcmd.3
index 4db847c392..87e9a760a8 100644
--- a/src/lib/libc/net/rcmd.3
+++ b/src/lib/libc/net/rcmd.3
@@ -1,4 +1,4 @@
-.\"     $NetBSD: rcmd.3,v 1.8 1995/02/25 06:20:52 cgd Exp $
+.\"     $OpenBSD: rcmd.3,v 1.27 2007/05/31 19:19:30 jmc Exp $
 .\"
 .\" Copyright (c) 1983, 1991, 1993
 .\"     The Regents of the University of California.  All rights reserved.
@@ -11,11 +11,7 @@
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\"    must display the following acknowledgement:
-.\"     This product includes software developed by the University of
-.\"     California, Berkeley and its contributors.
-.\" 4. Neither the name of the University nor the names of its contributors
+.\" 3. Neither the name of the University nor the names of its contributors
 .\"    may be used to endorse or promote products derived from this software
 .\"    without specific prior written permission.
 .\"
@@ -31,38 +27,67 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"     @(#)rcmd.3      8.1 (Berkeley) 6/4/93
-.\"
-.Dd June 4, 1993
+.Dd $Mdocdate: May 31 2007 $
 .Dt RCMD 3
-.Os BSD 4.2
+.Os
 .Sh NAME
 .Nm rcmd ,
+.Nm rcmd_af ,
 .Nm rresvport ,
+.Nm rresvport_af ,
 .Nm iruserok ,
-.Nm ruserok
+.Nm ruserok ,
+.Nm iruserok_sa
 .Nd routines for returning a stream to a remote command
 .Sh SYNOPSIS
 .Fd #include <unistd.h>
 .Ft int
 .Fn rcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p"
 .Ft int
+.Fn rcmd_af "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" "int af"
+.Ft int
 .Fn rresvport "int *port"
 .Ft int
-.Fn iruserok "u_long raddr" "int superuser" "const char *ruser" "const char *luser"
+.Fn rresvport_af "int *port" "int af"
+.Ft int
+.Fn iruserok "u_int32_t raddr" "int superuser" "const char *ruser" "const char *luser"
 .Ft int
 .Fn ruserok "const char *rhost" "int superuser" "const char *ruser" "const char *luser"
+.Ft int
+.Fn iruserok_sa "const void *sa" "int salen" "int superuser" "const char *ruser" "const char *luser"
 .Sh DESCRIPTION
 The
 .Fn rcmd
-function
-is used by the super-user to execute a command on
-a remote machine using an authentication scheme based
-on reserved port numbers.
+function is used by the superuser to execute a command on a remote
+machine using an authentication scheme based on reserved
+port numbers.
+If the calling process is not setuid, the
+.Ev RSH
+environment variable is set, and
+.Fa inport
+is
+.Dq shell/tcp ,
+.Xr rcmdsh 3
+is called instead with the value of
+.Ev RSH .
+Alternately, if the user is not the superuser,
+.Fn rcmd
+will invoke
+.Xr rcmdsh 3
+to run the command via
+.Xr rsh 1 .
+While
+.Fn rcmd
+can handle IPv4 cases only,
+the
+.Fn rcmd_af
+function can handle other cases as well.
+.Pp
 The
 .Fn rresvport
-function
-returns a descriptor to a socket
+and
+.Fn rresvport_af
+functions return a descriptor to a socket
 with an address in the privileged port space.
 The
 .Fn iruserok
@@ -75,11 +100,13 @@ All four functions are present in the same file and are used
 by the
 .Xr rshd 8
 server (among others).
+.Fn iruserok_sa
+is an address family independent variant of
+.Fn iruserok .
 .Pp
 The
 .Fn rcmd
-function
-looks up the host
+function looks up the host
 .Fa *ahost
 using
 .Xr gethostbyname 3 ,
@@ -90,15 +117,15 @@ is set to the standard name of the host
 and a connection is established to a server
 residing at the well-known Internet port
 .Fa inport .
+If the user is not the superuser, the only valid port is
+.Dq shell/tcp
+(usually port 514).
 .Pp
 If the connection succeeds,
 a socket in the Internet domain of type
 .Dv SOCK_STREAM
 is returned to the caller, and given to the remote
-command as 
-.Em stdin
-and
-.Em stdout .
+command as stdin and stdout.
 If
 .Fa fd2p
 is non-zero, then an auxiliary channel to a control
@@ -113,27 +140,46 @@ signal numbers, to be
 forwarded to the process group of the command.
 If
 .Fa fd2p
-is 0, then the 
-.Em stderr
-(unit 2 of the remote
-command) will be made the same as the 
-.Em stdout
-and no
-provision is made for sending arbitrary signals to the remote process,
-although you may be able to get its attention by using out-of-band data.
+is
+.Va NULL ,
+then the standard error (unit 2 of the remote command) will be made
+the same as the standard output and no provision is made for sending
+arbitrary signals to the remote process, although you may be able to
+get its attention by using out-of-band data.
+Note that if the user is not the superuser,
+.Fa fd2p
+must be
+.Va NULL .
+.Pp
+.Fn rcmd_af
+takes address family in the last argument.
+If the last argument is
+.Dv PF_UNSPEC ,
+interpretation of
+.Fa *ahost
+will obey the underlying address resolution like DNS.
 .Pp
 The protocol is described in detail in
 .Xr rshd 8 .
 .Pp
 The
 .Fn rresvport
-function is used to obtain a socket with a privileged
-address bound to it.  This socket is suitable for use
-by 
+and
+.Fn rresvport_af
+functions are used to obtain a socket with a privileged
+address bound to it.
+This socket is suitable for use by
 .Fn rcmd
-and several other functions.  Privileged Internet ports are those
-in the range 0 to 1023.  Only the super-user
-is allowed to bind an address of this sort to a socket.
+and several other functions.
+Privileged Internet ports are those in the range 0 to
+.Va IPPORT_RESERVED - 1 ,
+which happens to be 1023.
+Only the superuser is allowed to bind an address of this sort to a socket.
+.Fn rresvport
+and
+.Fn rresvport_af
+need to be seeded with a port number; if that port
+is not available these functions will find another.
 .Pp
 The
 .Fn iruserok
@@ -141,10 +187,10 @@ and
 .Fn ruserok
 functions take a remote host's IP address or name, respectively,
 two user names and a flag indicating whether the local user's
-name is that of the super-user.
+name is that of the superuser.
 Then, if the user is
-.Em NOT
-the super-user, it checks the
+.Em not
+the superuser, it checks the
 .Pa /etc/hosts.equiv
 file.
 If that lookup is not done, or is unsuccessful, the
@@ -153,19 +199,19 @@ in the local user's home directory is checked to see if the request for
 service is allowed.
 .Pp
 If this file does not exist, is not a regular file, is owned by anyone
-other than the user or the super-user, or is writeable by anyone other
+other than the user or the superuser, or is writeable by anyone other
 than the owner, the check automatically fails.
 Zero is returned if the machine name is listed in the
-.Dq Pa hosts.equiv
+.Pa hosts.equiv
 file, or the host and remote user name are found in the
-.Dq Pa .rhosts
+.Pa .rhosts
 file; otherwise
 .Fn iruserok
 and
 .Fn ruserok
 return \-1.
 If the local domain (as obtained from
-.Xr gethostname 2 )
+.Xr gethostname 3 )
 is the same as the remote domain, only the machine name need be specified.
 .Pp
 If the IP address of the remote host is known,
@@ -173,32 +219,48 @@ If the IP address of the remote host is known,
 should be used in preference to
 .Fn ruserok ,
 as it does not require trusting the DNS server for the remote host's domain.
+.Pp
+While
+.Fn iruserok
+can handle IPv4 addresses only,
+.Fn iruserok_sa
+and
+.Fn ruserok
+can handle other address families as well, like IPv6.
+The first argument of
+.Fn iruserok_sa
+is typed as
+.Li "void *"
+to avoid dependency between
+.Aq Pa unistd.h
+and
+.Aq Pa sys/socket.h .
 .Sh DIAGNOSTICS
 The
 .Fn rcmd
-function
-returns a valid socket descriptor on success.
+function returns a valid socket descriptor on success.
 It returns \-1 on error and prints a diagnostic message on the standard error.
 .Pp
 The
 .Fn rresvport
-function
-returns a valid, bound socket descriptor on success.
+and
+.Fn rresvport_af
+functions return a valid, bound socket descriptor on success.
 It returns \-1 on error with the global value
 .Va errno
 set according to the reason for failure.
 The error code
-.Dv EAGAIN
-is overloaded to mean ``All network ports in use.''
+.Er EAGAIN
+is overloaded to mean
+.Dq all network ports in use .
 .Sh SEE ALSO
-.Xr rlogin 1 ,
 .Xr rsh 1 ,
 .Xr intro 2 ,
-.Xr rexec 3 ,
-.Xr rexecd 8 ,
-.Xr rlogind 8 ,
+.Xr bindresvport 3 ,
+.Xr bindresvport_sa 3 ,
+.Xr rcmdsh 3 ,
 .Xr rshd 8
 .Sh HISTORY
 These
-functions appeared in 
+functions appeared in
 .Bx 4.2 .