original/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  2010-09-10 "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 CONFORMING TO
 131 These functions are GNU extensions.
 132 Functions with similar names exist on some other systems,
 133 though typically with different calling signatures.
 134 .SH EXAMPLE
 135 The program below uses
 136 .BR getservbyport_r ()
 137 to retrieve the service record for the port and protocol named
 138 in its first command-line argument.
 139 If a third (integer) command-line argument is supplied,
 140 it is used as the initial value for
 141 .IR buflen ;
 142 if
 143 .BR getservbyport_r ()
 144 fails with the error
 145 .BR ERANGE ,
 146 the program retries with larger buffer sizes.
 147 The following shell session shows a couple of sample runs:
 148 .in +4n
 149 .nf
 150
 151 .RB "$" " ./a.out 7 tcp 1"
 152 ERANGE! Retrying with larger buffer
 153 getservbyport_r() returned: 0 (success)  (buflen=87)
 154 s_name=echo; s_proto=tcp; s_port=7; aliases=
 155 .RB "$" " ./a.out 77777 tcp"
 156 getservbyport_r() returned: 0 (success)  (buflen=1024)
 157 Call failed/record not found
 158 .fi
 159 .in
 160 .SS Program source
 161 \&
 162 .nf
 163 #define _GNU_SOURCE
 164 #include <ctype.h>
 165 #include <netdb.h>
 166 #include <stdlib.h>
 167 #include <stdio.h>
 168 #include <errno.h>
 169 #include <string.h>
 170
 171 #define MAX_BUF 10000
 172
 173 int
 174 main(int argc, char *argv[])
 175 {
 176     int buflen, erange_cnt, port, s;
 177     struct servent result_buf;
 178     struct servent *result;
 179     char buf[MAX_BUF];
 180     char *protop;
 181     char **p;
 182
 183     if (argc < 3) {
 184         printf("Usage: %s port\-num proto\-name [buflen]\\n", argv[0]);
 185         exit(EXIT_FAILURE);
 186     }
 187
 188     port = htons(atoi(argv[1]));
 189     protop = (strcmp(argv[2], "null") == 0 ||
 190               strcmp(argv[2], "NULL") == 0) ?  NULL : argv[2];
 191
 192     buflen = 1024;
 193     if (argc > 3)
 194         buflen = atoi(argv[3]);
 195
 196     if (buflen > MAX_BUF) {
 197         printf("Exceeded buffer limit (%d)\\n", MAX_BUF);
 198         exit(EXIT_FAILURE);
 199     }
 200
 201     erange_cnt = 0;
 202     do {
 203         s = getservbyport_r(port, protop, &result_buf,
 204                      buf, buflen, &result);
 205         if (s == ERANGE) {
 206             if (erange_cnt == 0)
 207                 printf("ERANGE! Retrying with larger buffer\\n");
 208             erange_cnt++;
 209
 210             /* Increment a byte at a time so we can see exactly
 211                what size buffer was required */
 212
 213             buflen++;
 214
 215             if (buflen > MAX_BUF) {
 216                 printf("Exceeded buffer limit (%d)\\n", MAX_BUF);
 217                 exit(EXIT_FAILURE);
 218             }
 219         }
 220     } while (s == ERANGE);
 221
 222     printf("getservbyport_r() returned: %s  (buflen=%d)\\n",
 223             (s == 0) ? "0 (success)" : (s == ENOENT) ? "ENOENT" :
 224             strerror(s), buflen);
 225
 226     if (s != 0 || result == NULL) {
 227         printf("Call failed/record not found\\n");
 228         exit(EXIT_FAILURE);
 229     }
 230
 231     printf("s_name=%s; s_proto=%s; s_port=%d; aliases=",
 232                 result_buf.s_name, result_buf.s_proto,
 233                 ntohs(result_buf.s_port));
 234     for (p = result_buf.s_aliases; *p != NULL; p++)
 235         printf("%s ", *p);
 236     printf("\\n");
 237
 238     exit(EXIT_SUCCESS);
 239 }
 240 .fi
 241 .SH SEE ALSO
 242 .BR getservent (3),
 243 .BR services (5)
 244 .SH COLOPHON
 245 This page is part of release 3.79 of the Linux
 246 .I man-pages
 247 project.
 248 A description of the project,
 249 information about reporting bugs,
 250 and the latest version of this page,
 251 can be found at
 252 \%http://www.kernel.org/doc/man\-pages/.