getservent.3: Fix function name.
[dragonfly.git] / lib / libc / net / getservent.3
1 .\" Copyright (c) 1983, 1991, 1993
2 .\"     The Regents of the University of California.  All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\" 3. Neither the name of the University nor the names of its contributors
13 .\"    may be used to endorse or promote products derived from this software
14 .\"    without specific prior written permission.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .\" SUCH DAMAGE.
27 .\"
28 .\"     From: @(#)getservent.3  8.3 (Berkeley) 1/12/94
29 .\" $FreeBSD: src/lib/libc/net/getservent.3,v 1.15 2007/01/09 00:28:02 imp Exp $
30 .\"
31 .Dd May 4, 2019
32 .Dt GETSERVENT 3
33 .Os
34 .Sh NAME
35 .Nm getservent ,
36 .Nm getservent_r ,
37 .Nm getservbyport ,
38 .Nm getservbyport_r ,
39 .Nm getservbyname ,
40 .Nm getservbyname_r ,
41 .Nm setservent ,
42 .Nm endservent
43 .Nd get service entry
44 .Sh LIBRARY
45 .Lb libc
46 .Sh SYNOPSIS
47 .In netdb.h
48 .Ft struct servent *
49 .Fn getservent void
50 .Ft int
51 .Fn getservent_r "struct servent *" "char *" "size_t" "struct servent **"
52 .Ft struct servent *
53 .Fn getservbyname "const char *name" "const char *proto"
54 .Ft int
55 .Fn getservbyname_r "const char *" "const char *" "struct servent *" "char *" "size_t" "struct servent **"
56 .Ft struct servent *
57 .Fn getservbyport "int port" "const char *proto"
58 .Ft int
59 .Fn getservbyport_r "int" "const char *" "struct servent *" "char *" "size_t" "struct servent **"
60 .Ft void
61 .Fn setservent "int stayopen"
62 .Ft void
63 .Fn endservent void
64 .Sh DESCRIPTION
65 The
66 .Fn getservent ,
67 .Fn getservbyname ,
68 and
69 .Fn getservbyport
70 functions
71 each return a pointer to an object with the
72 following structure
73 containing the broken-out
74 fields of a line in the network services data base,
75 .Pa /etc/services .
76 .Bd -literal -offset indent
77 struct  servent {
78         char    *s_name;        /* official name of service */
79         char    **s_aliases;    /* alias list */
80         int     s_port;         /* port service resides at */
81         char    *s_proto;       /* protocol to use */
82 };
83 .Ed
84 .Pp
85 The members of this structure are:
86 .Bl -tag -width s_aliases
87 .It Fa s_name
88 The official name of the service.
89 .It Fa s_aliases
90 A zero terminated list of alternate names for the service.
91 .It Fa s_port
92 The port number at which the service resides.
93 Port numbers are returned in network byte order.
94 .It Fa s_proto
95 The name of the protocol to use when contacting the
96 service.
97 .El
98 .Pp
99 The
100 .Fn getservent
101 function
102 reads the next line of the file, opening the file if necessary.
103 .Pp
104 The
105 .Fn setservent
106 function
107 opens and rewinds the file.
108 If the
109 .Fa stayopen
110 flag is non-zero,
111 the net data base will not be closed after each call to
112 .Fn getservbyname
113 or
114 .Fn getservbyport .
115 .Pp
116 The
117 .Fn endservent
118 function
119 closes the file.
120 .Pp
121 The
122 .Fn getservbyname
123 and
124 .Fn getservbyport
125 functions
126 sequentially search from the beginning
127 of the file until a matching
128 protocol name or
129 port number (which must be specified in
130 network byte order) is found,
131 or until
132 .Dv EOF
133 is encountered.
134 If a protocol name is also supplied (non-
135 .Dv NULL ) ,
136 searches must also match the protocol.
137 .Pp
138 The
139 .Fn getservent_r ,
140 .Fn getservbyport_r ,
141 and
142 .Fn getservbyname_r
143 functions are reentrant versions of the above functions that take a
144 pointer to a
145 .Fa servent
146 structure which is used to store state information.
147 The structure must be zero-filled before it is used
148 and should be considered opaque for the sake of portability.
149 These functions also take a pointer to another
150 .Fa servent
151 structure which is used to store the results of the database lookup.
152 .Sh RETURN VALUES
153 The
154 .Fn getservent ,
155 .Fn getservbyport ,
156 and
157 .Fn getservbyname
158 functions return a pointer to a
159 .Vt servent
160 structure on success or a null pointer if end-of-file
161 is reached or an error occurs.
162 .Pp
163 The
164 .Fn getservent_r ,
165 .Fn getservbyport_r ,
166 and
167 .Fn getservbyname_r
168 functions return 0 on success or \-1 if end-of-file
169 is reached or an error occurs.
170 .Sh FILES
171 .Bl -tag -width ".Pa /etc/services" -compact
172 .It Pa /etc/services
173 .El
174 .Sh SEE ALSO
175 .Xr getprotoent 3 ,
176 .Xr services 5
177 .Sh STANDARDS
178 The
179 .Fn getservent ,
180 .Fn getservbyport ,
181 .Fn getservbyname ,
182 .Fn setservent ,
183 and
184 .Fn endservent
185 functions conform to
186 .St -p1003.1-2004 .
187 .Pp
188 The
189 .Fn getservent_r ,
190 .Fn getservbyport_r ,
191 and
192 .Fn getservbyname_r
193 functions are not currently standardized.
194 .Sh HISTORY
195 The
196 .Fn getservent ,
197 .Fn getservbyport ,
198 .Fn getservbyname ,
199 .Fn setservent ,
200 and
201 .Fn endservent
202 functions appeared in
203 .Bx 4.2 .
204 .Pp
205 The
206 .Fn getservent_r ,
207 .Fn getservbyport_r ,
208 and
209 .Fn getservbyname_r
210 functions appeared in
211 .Dx 2.1 .
212 .Sh BUGS
213 These functions use a thread-specific data storage;
214 if the data is needed for future use, it should be
215 copied before any subsequent calls overwrite it.
216 Expecting port numbers to fit in a 32 bit
217 quantity is probably naive.