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