man3/getservent_r.3

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