man3/getservent.3

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