1rcmd(3SOCKET)              Sockets Library Functions             rcmd(3SOCKET)
2
3
4

NAME

6       rcmd,  rcmd_af, rresvport, rresvport_af, ruserok - routines for return‐
7       ing a stream to a remote command
8

SYNOPSIS

10       cc [ flag ... ] file... -lsocket  -lnsl  [ library... ]
11       #include <netdb.h>
12       #include <unistd.h>
13
14       int rcmd(char **ahost, unsigned short inport, const char *luser,
15            const char *ruser, const char *cmd, int *fd2p);
16
17
18       int rcmd_af(char **ahost, unsigned short inport, const char *luser,
19            const char *ruser, const char *cmd, int *fd2p, int af);
20
21
22       int rresvport(int *port);
23
24
25       int rresvport_af(int *port, int af);
26
27
28       int ruserok(const char *rhost, int suser, const char *ruser,
29            const char *luser);
30
31

DESCRIPTION

33       The rcmd() function is used by the superuser to execute a command on  a
34       remote  machine  with  an  authentication scheme based on reserved port
35       numbers. An AF_INET socket is returned with rcmd(). The rcmd_af() func‐
36       tion supports AF_INET, AF_INET6 or AF_UNSPEC for the address family. An
37       application can choose which type of  socket  is  returned  by  passing
38       AF_INET  or  AF_INET6 as the address family. The use of AF_UNSPEC means
39       that the caller will accept any address family. Choosing AF_UNSPEC pro‐
40       vides a socket that best suits the connectivity to the remote host.
41
42
43       The  rresvport()  function  returns  a  descriptor  to a socket with an
44       address in the privileged port space. The  rresvport_af()  function  is
45       the  equivalent  to  rresvport(), except that you can choose AF_INET or
46       AF_INET6 as the socket address family to be returned by rresvport_af().
47       AF_UNSPEC does not apply to the rresvport() function.
48
49
50       The  ruserok()  function  is  a routine used by servers to authenticate
51       clients that request as service with rcmd.
52
53
54       All of these functions are present in the same file and are used by the
55       in.rshd(1M) server among others.
56
57
58       The rcmd() and rcmd_af() functions look up the host *ahost using getad‐
59       drinfo(3SOCKET) and return −1 if the host does  not  exist.  Otherwise,
60       *ahost  is  set  to  the  standard name of the host and a connection is
61       established to a server residing at the Internet port inport.
62
63
64       If the connection succeeds, a socket in the  Internet  domain  of  type
65       SOCK_STREAM  is  returned  to  the  caller.  The socket is given to the
66       remote command as standard input (file descriptor 0) and standard  out‐
67       put (file descriptor 1). If fd2p is non-zero, an auxiliary channel to a
68       control process is set up and a descriptor for it is placed  in  *fd2p.
69       The  control process returns diagnostic output file (descriptor 2) from
70       the command on the auxiliary channel. The control process also  accepts
71       bytes  on this channel as signal numbers to be forwarded to the process
72       group of the command. If fd2p is 0, the standard error (file descriptor
73       2)  of  the  remote command is made the same as its standard output. No
74       provision is made for sending arbitrary signals to the remote  process,
75       other than possibly sending out-of-band data.
76
77
78       The protocol is described in detail in in.rshd(1M).
79
80
81       The  rresvport()  and  rresvport_af()  functions  are  used to obtain a
82       socket bound to a privileged port number. The socket  is  suitable  for
83       use by rcmd() and rresvport_af() and several other routines. Privileged
84       Internet ports are those in the range 1 to 1023. Only the superuser  is
85       allowed  to  bind a socket to a privileged port number. The application
86       must pass in port, which must be in the range 512 to 1023.  The  system
87       first  tries to bind to that port number.  If it fails, the system then
88       tries to bind to another unused privileged port, if one is available.
89
90
91       The ruserok() function takes a remote host name returned by  the  geth‐
92       ostbyaddr() function with two user names and a flag to indicate whether
93       the local  user's  name  is  that  of  the  superuser.  See  gethostby‐
94       name(3NSL).    The   ruserok()   function   then   checks   the   files
95       /etc/hosts.equiv and possibly .rhosts in the local user's  home  direc‐
96       tory  to  see  if  the  request  for  service  is allowed. A 0 value is
97       returned if the machine name is listed in the /etc/hosts.equiv file, or
98       if  the host and remote user name are found in the .rhosts file. Other‐
99       wise, the ruserok() function returns −1. If the superuser  flag  is  1,
100       the /etc/hosts.equiv is not checked.
101
102
103       The error code EAGAIN is overloaded to mean "All network ports in use."
104

RETURN VALUES

106       The  rcmd()  and  rcmd_af()  functions return a valid socket descriptor
107       upon success. The functions returns −1 upon error and print a  diagnos‐
108       tic message to standard error.
109
110
111       The  rresvport()  and  rresvport_af()  functions  return a valid, bound
112       socket descriptor upon success. The functions return −1 upon error with
113       the global value errno set according to the reason for failure.
114

FILES

116       /etc/hosts.equiv    system trusted hosts and users
117
118
119       ~/.rhosts           user's trusted hosts and users
120
121

ATTRIBUTES

123       See attributes(5) for descriptions of the following attributes:
124
125
126
127
128       ┌─────────────────────────────┬─────────────────────────────┐
129       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
130       ├─────────────────────────────┼─────────────────────────────┤
131       │MT-Level                     │Unsafe                       │
132       └─────────────────────────────┴─────────────────────────────┘
133
134
135       This  interface  is Unsafe in multithreaded applications. Unsafe inter‐
136       faces should be called only from the main thread.
137

SEE ALSO

139       rlogin(1),  rsh(1),  in.rexecd(1M),   in.rshd(1M),   Intro(2),   getad‐
140       drinfo(3SOCKET), gethostbyname(3NSL), rexec(3SOCKET), attributes(5)
141
142
143
144SunOS 5.11                        10 Feb 2004                    rcmd(3SOCKET)
Impressum