man3/getservent.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" References consulted:
   6 .\"     Linux libc source code
   7 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   8 .\"     386BSD man pages
   9 .\" Modified Sat Jul 24 19:19:11 1993 by Rik Faith (faith@cs.unc.edu)
  10 .\" Modified Wed Oct 18 20:23:54 1995 by Martin Schulze <joey@infodrom.north.de>
  11 .\" Modified Mon Apr 22 01:50:54 1996 by Martin Schulze <joey@infodrom.north.de>
  12 .\" 2001-07-25 added a clause about NULL proto (Martin Michlmayr or David N. Welton)
  13 .\"
  14 .TH GETSERVENT 3 (date) "Linux man-pages (unreleased)"
  15 .SH NAME
  16 getservent, getservbyname, getservbyport, setservent, endservent \-
  17 get service entry
  18 .SH LIBRARY
  19 Standard C library
  20 .RI ( libc ", " \-lc )
  21 .SH SYNOPSIS
  22 .nf
  23 .B #include <netdb.h>
  24 .PP
  25 .B struct servent *getservent(void);
  26 .PP
  27 .BI "struct servent *getservbyname(const char *" name ", const char *" proto );
  28 .BI "struct servent *getservbyport(int " port ", const char *" proto );
  29 .PP
  30 .BI "void setservent(int " stayopen );
  31 .B void endservent(void);
  32 .fi
  33 .SH DESCRIPTION
  34 The
  35 .BR getservent ()
  36 function reads the next entry from the services database (see
  37 .BR services (5))
  38 and returns a
  39 .I servent
  40 structure containing
  41 the broken-out fields from the entry.
  42 A connection is opened to the database if necessary.
  43 .PP
  44 The
  45 .BR getservbyname ()
  46 function returns a
  47 .I servent
  48 structure
  49 for the entry from the database
  50 that matches the service
  51 .I name
  52 using protocol
  53 .IR proto .
  54 If
  55 .I proto
  56 is NULL, any protocol will be matched.
  57 A connection is opened to the database if necessary.
  58 .PP
  59 The
  60 .BR getservbyport ()
  61 function returns a
  62 .I servent
  63 structure
  64 for the entry from the database
  65 that matches the port
  66 .I port
  67 (given in network byte order)
  68 using protocol
  69 .IR proto .
  70 If
  71 .I proto
  72 is NULL, any protocol will be matched.
  73 A connection is opened to the database if necessary.
  74 .PP
  75 The
  76 .BR setservent ()
  77 function opens a connection to the database,
  78 and sets the next entry to the first entry.
  79 If
  80 .I stayopen
  81 is nonzero,
  82 then the connection to the database
  83 will not be closed between calls to one of the
  84 .BR getserv* ()
  85 functions.
  86 .PP
  87 The
  88 .BR endservent ()
  89 function closes the connection to the database.
  90 .PP
  91 The
  92 .I servent
  93 structure is defined in
  94 .I <netdb.h>
  95 as follows:
  96 .PP
  97 .in +4n
  98 .EX
  99 struct servent {
 100     char  *s_name;       /* official service name */
 101     char **s_aliases;    /* alias list */
 102     int    s_port;       /* port number */
 103     char  *s_proto;      /* protocol to use */
 104 }
 105 .EE
 106 .in
 107 .PP
 108 The members of the
 109 .I servent
 110 structure are:
 111 .TP
 112 .I s_name
 113 The official name of the service.
 114 .TP
 115 .I s_aliases
 116 A NULL-terminated list of alternative names for the service.
 117 .TP
 118 .I s_port
 119 The port number for the service given in network byte order.
 120 .TP
 121 .I s_proto
 122 The name of the protocol to use with this service.
 123 .SH RETURN VALUE
 124 The
 125 .BR getservent (),
 126 .BR getservbyname (),
 127 and
 128 .BR getservbyport ()
 129 functions return a pointer to a
 130 statically allocated
 131 .I servent
 132 structure, or NULL if an
 133 error occurs or the end of the file is reached.
 134 .SH FILES
 135 .TP
 136 .I /etc/services
 137 services database file
 138 .SH ATTRIBUTES
 139 For an explanation of the terms used in this section, see
 140 .BR attributes (7).
 141 .ad l
 142 .nh
 143 .TS
 144 allbox;
 145 lb lb lbx
 146 l l l.
 147 Interface       Attribute       Value
 148 T{
 149 .BR getservent ()
 150 T}      Thread safety   T{
 151 MT-Unsafe race:servent
 152 race:serventbuf locale
 153 T}
 154 T{
 155 .BR getservbyname ()
 156 T}      Thread safety   T{
 157 MT-Unsafe race:servbyname
 158 locale
 159 T}
 160 T{
 161 .BR getservbyport ()
 162 T}      Thread safety   T{
 163 MT-Unsafe race:servbyport
 164 locale
 165 T}
 166 T{
 167 .BR setservent (),
 168 .BR endservent ()
 169 T}      Thread safety   T{
 170 MT-Unsafe race:servent
 171 locale
 172 T}
 173 .TE
 174 .hy
 175 .ad
 176 .sp 1
 177 In the above table,
 178 .I servent
 179 in
 180 .I race:servent
 181 signifies that if any of the functions
 182 .BR setservent (),
 183 .BR getservent (),
 184 or
 185 .BR endservent ()
 186 are used in parallel in different threads of a program,
 187 then data races could occur.
 188 .SH STANDARDS
 189 POSIX.1-2001, POSIX.1-2008, 4.3BSD.
 190 .SH SEE ALSO
 191 .BR getnetent (3),
 192 .BR getprotoent (3),
 193 .BR getservent_r (3),
 194 .BR services (5)