git.saurik.com Git - apple/libinfo.git/blame

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