man3/getservent_r.3

   1 .\" Copyright 2008, Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .TH GETSERVENT_R 3  2015-07-23 "GNU" "Linux Programmer's Manual"
  27 .SH NAME
  28 getservent_r, getservbyname_r, getservbyport_r \- get
  29 service entry (reentrant)
  30 .SH SYNOPSIS
  31 .nf
  32 .B #include <netdb.h>
  33 .sp
  34 .BI "int getservent_r(struct servent *" result_buf ", char *" buf ,
  35 .BI "                size_t " buflen ", struct servent **" result );
  36 .sp
  37 .BI "int getservbyname_r(const char *" name ", const char *" proto ,
  38 .BI "                struct servent *" result_buf ", char *" buf ,
  39 .BI "                size_t " buflen ", struct servent **" result );
  40 .sp
  41 .BI "int getservbyport_r(int " port ", const char *" proto ,
  42 .BI "                struct servent *" result_buf ", char *" buf ,
  43 .BI "                size_t " buflen ", struct servent **" result );
  44 .sp
  45 .fi
  46 .in -4n
  47 Feature Test Macro Requirements for glibc (see
  48 .BR feature_test_macros (7)):
  49 .ad l
  50 .in
  51 .sp
  52 .BR getservent_r (),
  53 .BR getservbyname_r (),
  54 .BR getservbyport_r ():
  55 .RS 4
  56 _BSD_SOURCE || _SVID_SOURCE
  57 .RE
  58 .ad b
  59 .SH DESCRIPTION
  60 The
  61 .BR getservent_r (),
  62 .BR getservbyname_r (),
  63 and
  64 .BR getservbyport_r ()
  65 functions are the reentrant equivalents of, respectively,
  66 .BR getservent (3),
  67 .BR getservbyname (3),
  68 and
  69 .BR getservbyport (3).
  70 They differ in the way that the
  71 .I servent
  72 structure is returned,
  73 and in the function calling signature and return value.
  74 This manual page describes just the differences from
  75 the nonreentrant functions.
  76
  77 Instead of returning a pointer to a statically allocated
  78 .I servent
  79 structure as the function result,
  80 these functions copy the structure into the location pointed to by
  81 .IR result_buf .
  82
  83 The
  84 .I buf
  85 array is used to store the string fields pointed to by the returned
  86 .I servent
  87 structure.
  88 (The nonreentrant functions allocate these strings in static storage.)
  89 The size of this array is specified in
  90 .IR buflen .
  91 If
  92 .I buf
  93 is too small, the call fails with the error
  94 .BR ERANGE ,
  95 and the caller must try again with a larger buffer.
  96 (A buffer of length 1024 bytes should be sufficient for most applications.)
  97 .\" I can find no information on the required/recommended buffer size;
  98 .\" the nonreentrant functions use a 1024 byte buffer -- mtk.
  99
 100 If the function call successfully obtains a service record, then
 101 .I *result
 102 is set pointing to
 103 .IR result_buf ;
 104 otherwise,
 105 .I *result
 106 is set to NULL.
 107 .SH RETURN VALUE
 108 On success, these functions return 0.
 109 On error, they return one of the positive error numbers listed in errors.
 110
 111 On error, record not found
 112 .RB ( getservbyname_r (),
 113 .BR getservbyport_r ()),
 114 or end of input
 115 .RB ( getservent_r ())
 116 .I result
 117 is set to NULL.
 118 .SH ERRORS
 119 .TP
 120 .B ENOENT
 121 .RB ( getservent_r ())
 122 No more records in database.
 123 .TP
 124 .B ERANGE
 125 .I buf
 126 is too small.
 127 Try again with a larger buffer
 128 (and increased
 129 .IR buflen ).
 130 .SH ATTRIBUTES
 131 For an explanation of the terms used in this section, see
 132 .BR attributes (7).
 133 .TS
 134 allbox;
 135 lbw18 lb lb
 136 l l l.
 137 Interface       Attribute       Value
 138 T{
 139 .BR getservent_r (),
 140 .BR getservbyname_r (),
 141 .BR getservbyport_r ()
 142 T}      Thread safety   MT-Safe locale
 143 .TE
 144
 145 .SH CONFORMING TO
 146 These functions are GNU extensions.
 147 Functions with similar names exist on some other systems,
 148 though typically with different calling signatures.
 149 .SH EXAMPLE
 150 The program below uses
 151 .BR getservbyport_r ()
 152 to retrieve the service record for the port and protocol named
 153 in its first command-line argument.
 154 If a third (integer) command-line argument is supplied,
 155 it is used as the initial value for
 156 .IR buflen ;
 157 if
 158 .BR getservbyport_r ()
 159 fails with the error
 160 .BR ERANGE ,
 161 the program retries with larger buffer sizes.
 162 The following shell session shows a couple of sample runs:
 163 .in +4n
 164 .nf
 165
 166 .RB "$" " ./a.out 7 tcp 1"
 167 ERANGE! Retrying with larger buffer
 168 getservbyport_r() returned: 0 (success)  (buflen=87)
 169 s_name=echo; s_proto=tcp; s_port=7; aliases=
 170 .RB "$" " ./a.out 77777 tcp"
 171 getservbyport_r() returned: 0 (success)  (buflen=1024)
 172 Call failed/record not found
 173 .fi
 174 .in
 175 .SS Program source
 176 \&
 177 .nf
 178 #define _GNU_SOURCE
 179 #include <ctype.h>
 180 #include <netdb.h>
 181 #include <stdlib.h>
 182 #include <stdio.h>
 183 #include <errno.h>
 184 #include <string.h>
 185
 186 #define MAX_BUF 10000
 187
 188 int
 189 main(int argc, char *argv[])
 190 {
 191     int buflen, erange_cnt, port, s;
 192     struct servent result_buf;
 193     struct servent *result;
 194     char buf[MAX_BUF];
 195     char *protop;
 196     char **p;
 197
 198     if (argc < 3) {
 199         printf("Usage: %s port\-num proto\-name [buflen]\\n", argv[0]);
 200         exit(EXIT_FAILURE);
 201     }
 202
 203     port = htons(atoi(argv[1]));
 204     protop = (strcmp(argv[2], "null") == 0 ||
 205               strcmp(argv[2], "NULL") == 0) ?  NULL : argv[2];
 206
 207     buflen = 1024;
 208     if (argc > 3)
 209         buflen = atoi(argv[3]);
 210
 211     if (buflen > MAX_BUF) {
 212         printf("Exceeded buffer limit (%d)\\n", MAX_BUF);
 213         exit(EXIT_FAILURE);
 214     }
 215
 216     erange_cnt = 0;
 217     do {
 218         s = getservbyport_r(port, protop, &result_buf,
 219                      buf, buflen, &result);
 220         if (s == ERANGE) {
 221             if (erange_cnt == 0)
 222                 printf("ERANGE! Retrying with larger buffer\\n");
 223             erange_cnt++;
 224
 225             /* Increment a byte at a time so we can see exactly
 226                what size buffer was required */
 227
 228             buflen++;
 229
 230             if (buflen > MAX_BUF) {
 231                 printf("Exceeded buffer limit (%d)\\n", MAX_BUF);
 232                 exit(EXIT_FAILURE);
 233             }
 234         }
 235     } while (s == ERANGE);
 236
 237     printf("getservbyport_r() returned: %s  (buflen=%d)\\n",
 238             (s == 0) ? "0 (success)" : (s == ENOENT) ? "ENOENT" :
 239             strerror(s), buflen);
 240
 241     if (s != 0 || result == NULL) {
 242         printf("Call failed/record not found\\n");
 243         exit(EXIT_FAILURE);
 244     }
 245
 246     printf("s_name=%s; s_proto=%s; s_port=%d; aliases=",
 247                 result_buf.s_name, result_buf.s_proto,
 248                 ntohs(result_buf.s_port));
 249     for (p = result_buf.s_aliases; *p != NULL; p++)
 250         printf("%s ", *p);
 251     printf("\\n");
 252
 253     exit(EXIT_SUCCESS);
 254 }
 255 .fi
 256 .SH SEE ALSO
 257 .BR getservent (3),
 258 .BR services (5)