xref: /dragonfly/lib/libc/net/getservent.3 (revision d4ef6694) 
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 July 9, 1995
32.Dt GETSERVENT 3
33.Os
34.Sh NAME
35.Nm getservent ,
36.Nm getservbyport ,
37.Nm getservbyname ,
38.Nm setservent ,
39.Nm endservent
40.Nd get service entry
41.Sh LIBRARY
42.Lb libc
43.Sh SYNOPSIS
44.In netdb.h
45.Ft struct servent *
46.Fn getservent void
47.Ft struct servent *
48.Fn getservbyname "const char *name" "const char *proto"
49.Ft struct servent *
50.Fn getservbyport "int port" "const char *proto"
51.Ft void
52.Fn setservent "int stayopen"
53.Ft void
54.Fn endservent void
55.Sh DESCRIPTION
56The
57.Fn getservent ,
58.Fn getservbyname ,
59and
60.Fn getservbyport
61functions
62each return a pointer to an object with the
63following structure
64containing the broken-out
65fields of a line in the network services data base,
66.Pa /etc/services .
67.Bd -literal -offset indent
68struct	servent {
69	char	*s_name;	/* official name of service */
70	char	**s_aliases;	/* alias list */
71	int	s_port;		/* port service resides at */
72	char	*s_proto;	/* protocol to use */
73};
74.Ed
75.Pp
76The members of this structure are:
77.Bl -tag -width s_aliases
78.It Fa s_name
79The official name of the service.
80.It Fa s_aliases
81A zero terminated list of alternate names for the service.
82.It Fa s_port
83The port number at which the service resides.
84Port numbers are returned in network byte order.
85.It Fa s_proto
86The name of the protocol to use when contacting the
87service.
88.El
89.Pp
90The
91.Fn getservent
92function
93reads the next line of the file, opening the file if necessary.
94.Pp
95The
96.Fn setservent
97function
98opens and rewinds the file.
99If the
100.Fa stayopen
101flag is non-zero,
102the net data base will not be closed after each call to
103.Fn getservbyname
104or
105.Fn getservbyport .
106.Pp
107The
108.Fn endservent
109function
110closes the file.
111.Pp
112The
113.Fn getservbyname
114and
115.Fn getservbyport
116functions
117sequentially search from the beginning
118of the file until a matching
119protocol name or
120port number (which must be specified in
121network byte order) is found,
122or until
123.Dv EOF
124is encountered.
125If a protocol name is also supplied (non-
126.Dv NULL ) ,
127searches must also match the protocol.
128.Sh FILES
129.Bl -tag -width /etc/services -compact
130.It Pa /etc/services
131.El
132.Sh DIAGNOSTICS
133Null pointer
134(0) returned on
135.Dv EOF
136or error.
137.Sh SEE ALSO
138.Xr getprotoent 3 ,
139.Xr services 5
140.Sh HISTORY
141The
142.Fn getservent ,
143.Fn getservbyport ,
144.Fn getservbyname ,
145.Fn setservent ,
146and
147.Fn endservent
148functions appeared in
149.Bx 4.2 .
150.Sh BUGS
151These functions use a thread-specific data storage;
152if the data is needed for future use, it should be
153copied before any subsequent calls overwrite it.
154Expecting port numbers to fit in a 32 bit
155quantity is probably naive.
156