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 .P
  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 .P
  32 .fi
  33 .RS -4
  34 Feature Test Macro Requirements for glibc (see
  35 .BR feature_test_macros (7)):
  36 .RE
  37 .P
  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 .P
  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 .P
  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 .P
  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 .P
  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 .TS
 122 allbox;
 123 lbx lb lb
 124 l l l.
 125 Interface       Attribute       Value
 126 T{
 127 .na
 128 .nh
 129 .BR getservent_r (),
 130 .BR getservbyname_r (),
 131 .BR getservbyport_r ()
 132 T}      Thread safety   MT-Safe locale
 133 .TE
 134 .SH VERSIONS
 135 Functions with similar names exist on some other systems,
 136 though typically with different calling signatures.
 137 .SH STANDARDS
 138 GNU.
 139 .SH EXAMPLES
 140 The program below uses
 141 .BR getservbyport_r ()
 142 to retrieve the service record for the port and protocol named
 143 in its first command-line argument.
 144 If a third (integer) command-line argument is supplied,
 145 it is used as the initial value for
 146 .IR buflen ;
 147 if
 148 .BR getservbyport_r ()
 149 fails with the error
 150 .BR ERANGE ,
 151 the program retries with larger buffer sizes.
 152 The following shell session shows a couple of sample runs:
 153 .P
 154 .in +4n
 155 .EX
 156 .RB "$" " ./a.out 7 tcp 1"
 157 ERANGE! Retrying with larger buffer
 158 getservbyport_r() returned: 0 (success)  (buflen=87)
 159 s_name=echo; s_proto=tcp; s_port=7; aliases=
 160 .RB "$" " ./a.out 77777 tcp"
 161 getservbyport_r() returned: 0 (success)  (buflen=1024)
 162 Call failed/record not found
 163 .EE
 164 .in
 165 .SS Program source
 166 \&
 167 .\" SRC BEGIN (getservent_r.c)
 168 .EX
 169 #define _GNU_SOURCE
 170 #include <ctype.h>
 171 #include <errno.h>
 172 #include <netdb.h>
 173 #include <stdio.h>
 174 #include <stdlib.h>
 175 #include <string.h>
 176 \&
 177 #define MAX_BUF 10000
 178 \&
 179 int
 180 main(int argc, char *argv[])
 181 {
 182     int buflen, erange_cnt, port, s;
 183     struct servent result_buf;
 184     struct servent *result;
 185     char buf[MAX_BUF];
 186     char *protop;
 187 \&
 188     if (argc < 3) {
 189         printf("Usage: %s port\-num proto\-name [buflen]\en", argv[0]);
 190         exit(EXIT_FAILURE);
 191     }
 192 \&
 193     port = htons(atoi(argv[1]));
 194     protop = (strcmp(argv[2], "null") == 0 ||
 195               strcmp(argv[2], "NULL") == 0) ?  NULL : argv[2];
 196 \&
 197     buflen = 1024;
 198     if (argc > 3)
 199         buflen = atoi(argv[3]);
 200 \&
 201     if (buflen > MAX_BUF) {
 202         printf("Exceeded buffer limit (%d)\en", MAX_BUF);
 203         exit(EXIT_FAILURE);
 204     }
 205 \&
 206     erange_cnt = 0;
 207     do {
 208         s = getservbyport_r(port, protop, &result_buf,
 209                             buf, buflen, &result);
 210         if (s == ERANGE) {
 211             if (erange_cnt == 0)
 212                 printf("ERANGE! Retrying with larger buffer\en");
 213             erange_cnt++;
 214 \&
 215             /* Increment a byte at a time so we can see exactly
 216                what size buffer was required. */
 217 \&
 218             buflen++;
 219 \&
 220             if (buflen > MAX_BUF) {
 221                 printf("Exceeded buffer limit (%d)\en", MAX_BUF);
 222                 exit(EXIT_FAILURE);
 223             }
 224         }
 225     } while (s == ERANGE);
 226 \&
 227     printf("getservbyport_r() returned: %s  (buflen=%d)\en",
 228            (s == 0) ? "0 (success)" : (s == ENOENT) ? "ENOENT" :
 229            strerror(s), buflen);
 230 \&
 231     if (s != 0 || result == NULL) {
 232         printf("Call failed/record not found\en");
 233         exit(EXIT_FAILURE);
 234     }
 235 \&
 236     printf("s_name=%s; s_proto=%s; s_port=%d; aliases=",
 237            result_buf.s_name, result_buf.s_proto,
 238            ntohs(result_buf.s_port));
 239     for (char **p = result_buf.s_aliases; *p != NULL; p++)
 240         printf("%s ", *p);
 241     printf("\en");
 242 \&
 243     exit(EXIT_SUCCESS);
 244 }
 245 .EE
 246 .\" SRC END
 247 .SH SEE ALSO
 248 .BR getservent (3),
 249 .BR services (5)