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. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     From: @(#)getservent.3  8.3 (Berkeley) 1/12/94
  33 .\" $FreeBSD: src/lib/libc/net/getservent.3,v 1.7.2.5 2001/12/14 18:33:55 ru Exp $
  34 .\"
  35 .Dd July 9, 1995
  36 .Dt GETSERVENT 3
  37 .Os
  38 .Sh NAME
  39 .Nm getservent ,
  40 .Nm getservbyport ,
  41 .Nm getservbyname ,
  42 .Nm setservent ,
  43 .Nm endservent
  44 .Nd get service entry
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In netdb.h
  49 .Ft struct servent *
  50 .Fn getservent
  51 .Ft struct servent *
  52 .Fn getservbyname "const char *name" "const char *proto"
  53 .Ft struct servent *
  54 .Fn getservbyport "int port" "const char *proto"
  55 .Ft void
  56 .Fn setservent "int stayopen"
  57 .Ft void
  58 .Fn endservent void
  59 .Sh DESCRIPTION
  60 The
  61 .Fn getservent ,
  62 .Fn getservbyname ,
  63 and
  64 .Fn getservbyport
  65 functions
  66 each return a pointer to an object with the
  67 following structure
  68 containing the broken-out
  69 fields of a line in the network services data base,
  70 .Pa /etc/services .
  71 .Bd -literal -offset indent
  72 struct  servent {
  73         char    *s_name;        /* official name of service */
  74         char    **s_aliases;    /* alias list */
  75         int     s_port;         /* port service resides at */
  76         char    *s_proto;       /* protocol to use */
  77 };
  78 .Ed
  79 .Pp
  80 The members of this structure are:
  81 .Bl -tag -width s_aliases
  82 .It Fa s_name
  83 The official name of the service.
  84 .It Fa s_aliases
  85 A zero terminated list of alternate names for the service.
  86 .It Fa s_port
  87 The port number at which the service resides.
  88 Port numbers are returned in network byte order.
  89 .It Fa s_proto
  90 The name of the protocol to use when contacting the
  91 service.
  92 .El
  93 .Pp
  94 The
  95 .Fn getservent
  96 function
  97 reads the next line of the file, opening the file if necessary.
  98 .Pp
  99 The
 100 .Fn setservent
 101 function
 102 opens and rewinds the file.  If the
 103 .Fa stayopen
 104 flag is non-zero,
 105 the net data base will not be closed after each call to
 106 .Fn getservbyname
 107 or
 108 .Fn getservbyport .
 109 .Pp
 110 The
 111 .Fn endservent
 112 function
 113 closes the file.
 114 .Pp
 115 The
 116 .Fn getservbyname
 117 and
 118 .Fn getservbyport
 119 functions
 120 sequentially search from the beginning
 121 of the file until a matching
 122 protocol name or
 123 port number (which must be specified in
 124 network byte order) is found,
 125 or until
 126 .Dv EOF
 127 is encountered.
 128 If a protocol name is also supplied (non-
 129 .Dv NULL ) ,
 130 searches must also match the protocol.
 131 .Sh FILES
 132 .Bl -tag -width /etc/services -compact
 133 .It Pa /etc/services
 134 .El
 135 .Sh DIAGNOSTICS
 136 Null pointer
 137 (0) returned on
 138 .Dv EOF
 139 or error.
 140 .Sh SEE ALSO
 141 .Xr getprotoent 3 ,
 142 .Xr services 5
 143 .Sh HISTORY
 144 The
 145 .Fn getservent ,
 146 .Fn getservbyport ,
 147 .Fn getservbyname ,
 148 .Fn setservent ,
 149 and
 150 .Fn endservent
 151 functions appeared in
 152 .Bx 4.2 .
 153 .Sh BUGS
 154 These functions use static data storage;
 155 if the data is needed for future use, it should be
 156 copied before any subsequent calls overwrite it.
 157 Expecting port numbers to fit in a 32 bit
 158 quantity is probably naive.