man3/getrpcent_r.3

   1 .\" Copyright 2008, Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH GETRPCENT_R 3  2021-03-22 "Linux man-pages (unreleased)"
   7 .SH NAME
   8 getrpcent_r, getrpcbyname_r, getrpcbynumber_r \- get
   9 RPC entry (reentrant)
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <netdb.h>
  16 .PP
  17 .BI "int getrpcent_r(struct rpcent *" result_buf ", char *" buf ,
  18 .BI "                size_t " buflen ", struct rpcent **" result );
  19 .BI "int getrpcbyname_r(const char *" name ,
  20 .BI "                struct rpcent *" result_buf ", char *" buf ,
  21 .BI "                size_t " buflen ", struct rpcent **" result );
  22 .BI "int getrpcbynumber_r(int " number ,
  23 .BI "                struct rpcent *" result_buf ", char *" buf ,
  24 .BI "                size_t " buflen ", struct rpcent **" result );
  25 .PP
  26 .fi
  27 .RS -4
  28 Feature Test Macro Requirements for glibc (see
  29 .BR feature_test_macros (7)):
  30 .RE
  31 .PP
  32 .BR getrpcent_r (),
  33 .BR getrpcbyname_r (),
  34 .BR getrpcbynumber_r ():
  35 .nf
  36     Since glibc 2.19:
  37         _DEFAULT_SOURCE
  38     Glibc 2.19 and earlier:
  39         _BSD_SOURCE || _SVID_SOURCE
  40 .fi
  41 .SH DESCRIPTION
  42 The
  43 .BR getrpcent_r (),
  44 .BR getrpcbyname_r (),
  45 and
  46 .BR getrpcbynumber_r ()
  47 functions are the reentrant equivalents of, respectively,
  48 .BR getrpcent (3),
  49 .BR getrpcbyname (3),
  50 and
  51 .BR getrpcbynumber (3).
  52 They differ in the way that the
  53 .I rpcent
  54 structure is returned,
  55 and in the function calling signature and return value.
  56 This manual page describes just the differences from
  57 the nonreentrant functions.
  58 .PP
  59 Instead of returning a pointer to a statically allocated
  60 .I rpcent
  61 structure as the function result,
  62 these functions copy the structure into the location pointed to by
  63 .IR result_buf .
  64 .PP
  65 The
  66 .I buf
  67 array is used to store the string fields pointed to by the returned
  68 .I rpcent
  69 structure.
  70 (The nonreentrant functions allocate these strings in static storage.)
  71 The size of this array is specified in
  72 .IR buflen .
  73 If
  74 .I buf
  75 is too small, the call fails with the error
  76 .BR ERANGE ,
  77 and the caller must try again with a larger buffer.
  78 (A buffer of length 1024 bytes should be sufficient for most applications.)
  79 .\" I can find no information on the required/recommended buffer size;
  80 .\" the nonreentrant functions use a 1024 byte buffer -- mtk.
  81 .PP
  82 If the function call successfully obtains an RPC record, then
  83 .I *result
  84 is set pointing to
  85 .IR result_buf ;
  86 otherwise,
  87 .I *result
  88 is set to NULL.
  89 .SH RETURN VALUE
  90 On success, these functions return 0.
  91 On error, they return one of the positive error numbers listed in ERRORS.
  92 .PP
  93 On error, record not found
  94 .RB ( getrpcbyname_r (),
  95 .BR getrpcbynumber_r ()),
  96 or end of input
  97 .RB ( getrpcent_r ())
  98 .I result
  99 is set to NULL.
 100 .SH ERRORS
 101 .TP
 102 .B ENOENT
 103 .RB ( getrpcent_r ())
 104 No more records in database.
 105 .TP
 106 .B ERANGE
 107 .I buf
 108 is too small.
 109 Try again with a larger buffer
 110 (and increased
 111 .IR buflen ).
 112 .SH ATTRIBUTES
 113 For an explanation of the terms used in this section, see
 114 .BR attributes (7).
 115 .ad l
 116 .nh
 117 .TS
 118 allbox;
 119 lbx lb lb
 120 l l l.
 121 Interface       Attribute       Value
 122 T{
 123 .BR getrpcent_r (),
 124 .BR getrpcbyname_r (),
 125 .BR getrpcbynumber_r ()
 126 T}      Thread safety   MT-Safe locale
 127 .TE
 128 .hy
 129 .ad
 130 .sp 1
 131 .SH STANDARDS
 132 These functions are GNU extensions.
 133 Functions with similar names exist on some other systems,
 134 though typically with different calling signatures.
 135 .SH SEE ALSO
 136 .BR getrpcent (3),
 137 .BR rpc (5)