2 .\" $NetBSD: rcmd.3,v 1.9 1996/05/28 02:07:39 mrg Exp $
4 .\" Copyright (c) 1983, 1991, 1993
5 .\" The Regents of the University of California. All rights reserved.
7 .\" SPDX-License-Identifier: BSD-4-Clause-UC
9 .\" @(#)rcmd.3 8.1 (Berkeley) 6/4/93
11 .\" Contributed as Linux man page by David A. Holland, 970908
12 .\" I have not checked whether the Linux situation is exactly the same.
14 .\" 2007-12-08, mtk, Converted from mdoc to man macros
16 .TH rcmd 3 (date) "Linux man-pages (unreleased)"
18 rcmd, rresvport, iruserok, ruserok, rcmd_af,
19 rresvport_af, iruserok_af, ruserok_af \- routines for returning a
20 stream to a remote command
23 .RI ( libc ", " \-lc )
26 .BR "#include <netdb.h> " "/* Or <unistd.h> on some systems */"
28 .BI "int rcmd(char **restrict " ahost ", unsigned short " inport ,
29 .BI " const char *restrict " locuser ,
30 .BI " const char *restrict " remuser ,
31 .BI " const char *restrict " cmd ", int *restrict " fd2p );
33 .BI "int rresvport(int *" port );
35 .BI "int iruserok(uint32_t " raddr ", int " superuser ,
36 .BI " const char *" ruser ", const char *" luser );
37 .BI "int ruserok(const char *" rhost ", int " superuser ,
38 .BI " const char *" ruser ", const char *" luser );
40 .BI "int rcmd_af(char **restrict " ahost ", unsigned short " inport ,
41 .BI " const char *restrict " locuser ,
42 .BI " const char *restrict " remuser ,
43 .BI " const char *restrict " cmd ", int *restrict " fd2p ,
44 .BI " sa_family_t " af );
46 .BI "int rresvport_af(int *" port ", sa_family_t " af );
48 .BI "int iruserok_af(const void *restrict " raddr ", int " superuser ,
49 .BI " const char *restrict " ruser ", const char *restrict " luser ,
50 .BI " sa_family_t " af );
51 .BI "int ruserok_af(const char *" rhost ", int " superuser ,
52 .BI " const char *" ruser ", const char *" luser ,
53 .BI " sa_family_t " af );
57 Feature Test Macro Requirements for glibc (see
58 .BR feature_test_macros (7)):
73 glibc 2.19 and earlier:
80 function is used by the superuser to execute a command on
81 a remote machine using an authentication scheme based
82 on privileged port numbers.
86 returns a file descriptor to a socket
87 with an address in the privileged port space.
92 functions are used by servers
93 to authenticate clients requesting service with
95 All four functions are used by the
97 server (among others).
105 .BR gethostbyname (3),
106 returning \-1 if the host does not exist.
109 is set to the standard name of the host
110 and a connection is established to a server
111 residing at the well-known Internet port
114 If the connection succeeds,
115 a socket in the Internet domain of type
117 is returned to the caller, and given to the remote
124 is nonzero, then an auxiliary channel to a control
125 process will be set up, and a file descriptor for it will be placed
128 The control process will return diagnostic
129 output from the command (unit 2) on this channel, and will also
130 accept bytes on this channel as being UNIX signal numbers, to be
131 forwarded to the process group of the command.
136 (unit 2 of the remote
137 command) will be made the same as the
140 provision is made for sending arbitrary signals to the remote process,
141 although you may be able to get its attention by using out-of-band data.
143 The protocol is described in detail in
148 function is used to obtain a socket with a privileged
150 This socket is suitable for use by
152 and several other functions.
153 Privileged ports are those in the range 0 to 1023.
154 Only a privileged process
155 (on Linux, a process that has the
156 .B CAP_NET_BIND_SERVICE
157 capability in the user namespace governing its network namespace)
158 is allowed to bind to a privileged port.
159 In the glibc implementation,
160 this function restricts its search to the ports from 512 to 1023.
163 argument is value-result:
164 the value it supplies to the call is used as the starting point
165 for a circular search of the port range;
166 on (successful) return, it contains the port number that was bound to.
168 .SS iruserok() and ruserok()
173 functions take a remote host's IP address or name, respectively,
174 two usernames and a flag indicating whether the local user's
175 name is that of the superuser.
178 the superuser, it checks the
181 If that lookup is not done, or is unsuccessful, the
183 in the local user's home directory is checked to see if the request for
186 If this file does not exist, is not a regular file, is owned by anyone
187 other than the user or the superuser, is writable by anyone other
188 than the owner, or is hardlinked anywhere, the check automatically fails.
189 Zero is returned if the machine name is listed in the
191 file, or the host and remote username are found in the
198 If the local domain (as obtained from
200 is the same as the remote domain, only the machine name need be specified.
202 If the IP address of the remote host is known,
204 should be used in preference to
206 as it does not require trusting the DNS server for the remote host's domain.
208 All of the functions described above work with IPv4
211 The "_af" variants take an extra argument that allows the
212 socket address family to be specified.
213 For these functions, the
215 argument can be specified as
227 returns a valid socket descriptor on success.
228 It returns \-1 on error and prints a diagnostic message on the standard error.
233 returns a valid, bound socket descriptor on success.
234 On failure, it returns \-1 and sets
236 to indicate the error.
239 is overloaded to mean: "All network ports in use".
241 For information on the return from
247 For an explanation of the terms used in this section, see
253 Interface Attribute Value
259 T} Thread safety MT-Unsafe
265 T} Thread safety MT-Safe
273 T} Thread safety MT-Safe locale
290 The "_af" variants are more recent additions,
291 and are not present on as wide a range of systems.
296 are declared in glibc headers only since glibc 2.12.
297 .\" Bug filed 25 Nov 2007:
298 .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=5399