usr/src/man/man3socket/getnetbyname.3socket

   1 '\" te
   2 .\" Copyright (C) 2004, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" Copyright (c) 1983 Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement  specifies the terms and conditions for redistribution.
   5 .TH GETNETBYNAME 3SOCKET "Nov 4, 2004"
   6 .SH NAME
   7 getnetbyname, getnetbyname_r, getnetbyaddr, getnetbyaddr_r, getnetent,
   8 getnetent_r, setnetent, endnetent \- get network entry
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ]
  13 #include <netdb.h>
  14
  15 \fBstruct netent *\fR\fBgetnetbyname\fR(\fBconst char *\fR\fIname\fR);
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fBstruct netent *\fR\fBgetnetbyname_r\fR(\fBconst char *\fR\fIname\fR, \fBstruct netent *\fR\fIresult\fR,
  21      \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBstruct netent *\fR\fBgetnetbyaddr\fR(\fBlong\fR \fInet\fR, \fBint\fR \fItype\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBstruct netent *\fR\fBgetnetbyaddr_r\fR(\fBlong\fR \fInet\fR, \fBint\fR \fItype\fR, \fBstruct netent *\fR\fIresult\fR,
  32      \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR);
  33 .fi
  34
  35 .LP
  36 .nf
  37 \fBstruct netent *\fR\fBgetnetent\fR(\fBvoid\fR);
  38 .fi
  39
  40 .LP
  41 .nf
  42 \fBstruct netent *\fR\fBgetnetent_r\fR(\fBstruct netent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR,
  43      \fBint\fR \fIbuflen\fR);
  44 .fi
  45
  46 .LP
  47 .nf
  48 \fBint\fR \fBsetnetent\fR(\fBint\fR \fIstayopen\fR);
  49 .fi
  50
  51 .LP
  52 .nf
  53 \fBint\fR \fBendnetent\fR(\fBvoid\fR);
  54 .fi
  55
  56 .SH DESCRIPTION
  57 .sp
  58 .LP
  59 These functions are used to obtain entries for networks. An entry may come from
  60 any of the sources for \fBnetworks\fR specified in the \fB/etc/nsswitch.conf\fR
  61 file. See \fBnsswitch.conf\fR(4).
  62 .sp
  63 .LP
  64 \fBgetnetbyname()\fR searches for a network entry with the network name
  65 specified by the character string parameter \fIname\fR.
  66 .sp
  67 .LP
  68 \fBgetnetbyaddr()\fR searches for a network entry with the network address
  69 specified by \fInet\fR. The parameter \fBtype\fR specifies the family of the
  70 address. This should be one of the address families defined in
  71 <\fBsys/socket.h\fR>. See the \fBNOTES\fR section below for more information.
  72 .sp
  73 .LP
  74 Network numbers and local address parts are returned as machine format integer
  75 values, that is, in host byte order. See also \fBinet\fR(3SOCKET).
  76 .sp
  77 .LP
  78 The \fBnetent.n_net\fR member in the \fBnetent\fR structure pointed to by the
  79 return value of the above functions is calculated by \fBinet_network()\fR. The
  80 \fBinet_network()\fR function returns a value in host byte order that is
  81 aligned based upon the input string. For example:
  82 .sp
  83
  84 .sp
  85 .TS
  86 c c
  87 l l .
  88 Text    Value
  89 \fB"10"\fR      \fB0x0000000a\fR
  90 \fB"10.0"\fR    \fB0x00000a00\fR
  91 \fB"10.0.1"\fR  \fB0a000a0001\fR
  92 \fB"10.0.1.28\fR"       \fB0x0a000180\fR
  93 .TE
  94
  95 .sp
  96 .LP
  97 Commonly, the alignment of the returned value is used as a crude approximate of
  98 pre-CIDR (Classless Inter-Domain Routing) subnet mask. For example:
  99 .sp
 100 .in +2
 101 .nf
 102 in_addr_t addr, mask;
 103
 104 addr = inet_network(net_name);
 105 mask= ~(in_addr_t)0;
 106 if ((addr & IN_CLASSA_NET) == 0)
 107        addr <<= 8, mask <<= 8;
 108 if ((addr & IN_CLASSA_NET) == 0)
 109        addr <<= 8, mask <<= 8;
 110 if ((addr & IN_CLASSA_NET) == 0)
 111        addr <<= 8, mask <<= 8;
 112 .fi
 113 .in -2
 114
 115 .sp
 116 .LP
 117 This usage is deprecated by the CIDR requirements. See Fuller, V., Li, T., Yu,
 118 J., and Varadhan, K. \fIRFC 1519, Classless Inter-Domain Routing (CIDR): an
 119 Address Assignment and Aggregation Strategy\fR. Network Working Group.
 120 September 1993.
 121 .sp
 122 .LP
 123 The functions \fBsetnetent()\fR, \fBgetnetent()\fR, and \fBendnetent()\fR are
 124 used to enumerate network entries from the database.
 125 .sp
 126 .LP
 127 \fBsetnetent()\fR sets (or resets) the enumeration to the beginning of the set
 128 of network entries. This function should be called before the first call to
 129 \fBgetnetent()\fR. Calls to \fBgetnetbyname()\fR and \fBgetnetbyaddr()\fR leave
 130 the enumeration position in an indeterminate state. If the \fIstayopen\fR flag
 131 is non-zero, the system may keep allocated resources such as open file
 132 descriptors until a subsequent call to \fBendnetent()\fR.
 133 .sp
 134 .LP
 135 Successive calls to \fBgetnetent()\fR return either successive entries or
 136 \fBNULL\fR, indicating the end of the enumeration.
 137 .sp
 138 .LP
 139 \fBendnetent()\fR may be called to indicate that the caller expects to do no
 140 further network entry retrieval operations; the system may then deallocate
 141 resources it was using. It is still allowed, but possibly less efficient, for
 142 the process to call more network entry retrieval functions after calling
 143 \fBendnetent()\fR.
 144 .SS "Reentrant Interfaces"
 145 .sp
 146 .LP
 147 The functions \fBgetnetbyname()\fR, \fBgetnetbyaddr()\fR, and \fBgetnetent()\fR
 148 use static storage that is reused in each call, making these routines unsafe
 149 for use in multi-threaded applications.
 150 .sp
 151 .LP
 152 The functions \fBgetnetbyname_r()\fR, \fBgetnetbyaddr_r()\fR, and
 153 \fBgetnetent_r()\fR provide reentrant interfaces for these operations.
 154 .sp
 155 .LP
 156 Each reentrant interface performs the same operation as its non-reentrant
 157 counterpart, named by removing the ``\fB_r\fR'' suffix. The reentrant
 158 interfaces, however, use buffers supplied by the caller to store returned
 159 results, and are safe for use in both single-threaded and multi-threaded
 160 applications.
 161 .sp
 162 .LP
 163 Each reentrant interface takes the same parameters as its non-reentrant
 164 counterpart, as well as the following additional parameters. The parameter
 165 \fIresult\fR must be a pointer to a \fBstruct netent\fR structure allocated by
 166 the caller. On successful completion, the function returns the network entry in
 167 this structure. The parameter \fIbuffer\fR must be a pointer to a buffer
 168 supplied by the caller. This buffer is used as storage space for the network
 169 entry data. All of the pointers within the returned \fBstruct netent\fR
 170 \fIresult\fR point to data stored within this buffer. See \fBRETURN VALUES\fR.
 171 The buffer must be large enough to hold all of the data associated with the
 172 network entry. The parameter \fIbuflen\fR should give the size in bytes of the
 173 buffer indicated by \fIbuffer\fR.
 174 .sp
 175 .LP
 176 For enumeration in multi-threaded applications, the position within the
 177 enumeration is a process-wide property shared by all threads. \fBsetnetent()\fR
 178 may be used in a multi-threaded application but resets the enumeration position
 179 for all threads. If multiple threads interleave calls to \fBgetnetent_r()\fR,
 180 the threads will enumerate disjointed subsets of the network database.
 181 .sp
 182 .LP
 183 Like their non-reentrant counterparts, \fBgetnetbyname_r()\fR and
 184 \fBgetnetbyaddr_r()\fR leave the enumeration position in an indeterminate
 185 state.
 186 .SH RETURN VALUES
 187 .sp
 188 .LP
 189 Network entries are represented by the \fBstruct netent\fR structure defined in
 190 \fB<netdb.h>\fR\&.
 191 .sp
 192 .LP
 193 The functions \fBgetnetbyname()\fR, \fBgetnetbyname_r\fR, \fBgetnetbyaddr\fR,
 194 and \fBgetnetbyaddr_r()\fR each return a pointer to a \fBstruct netent\fR if
 195 they successfully locate the requested entry; otherwise they return \fBNULL\fR.
 196 .sp
 197 .LP
 198 The functions \fBgetnetent()\fR and \fBgetnetent_r()\fR each return a pointer
 199 to a \fBstruct netent\fR if they successfully enumerate an entry; otherwise
 200 they return \fBNULL\fR, indicating the end of the enumeration.
 201 .sp
 202 .LP
 203 The functions \fBgetnetbyname()\fR, \fBgetnetbyaddr()\fR, and \fBgetnetent()\fR
 204 use static storage, so returned data must be copied before a subsequent call to
 205 any of these functions if the data is to be saved.
 206 .sp
 207 .LP
 208 When the pointer returned by the reentrant functions \fBgetnetbyname_r()\fR,
 209 \fBgetnetbyaddr_r()\fR, and \fBgetnetent_r()\fR is non-\fBNULL\fR, it is always
 210 equal to the \fIresult\fR pointer that was supplied by the caller.
 211 .sp
 212 .LP
 213 The functions \fBsetnetent()\fR and \fBendnetent()\fR return \fB0\fR on
 214 success.
 215 .SH ERRORS
 216 .sp
 217 .LP
 218 The reentrant functions \fBgetnetbyname_r()\fR, \fBgetnetbyaddr_r\fR and
 219 \fBgetnetent_r()\fR will return \fBNULL\fR and set \fIerrno\fR to \fBERANGE\fR
 220 if the length of the buffer supplied by caller is not large enough to store the
 221 result. See \fBIntro\fR(2) for the proper usage and interpretation of
 222 \fIerrno\fR in multi-threaded applications.
 223 .SH FILES
 224 .sp
 225 .ne 2
 226 .na
 227 \fB\fB/etc/networks\fR\fR
 228 .ad
 229 .RS 22n
 230 network name database
 231 .RE
 232
 233 .sp
 234 .ne 2
 235 .na
 236 \fB\fB/etc/nsswitch.conf\fR\fR
 237 .ad
 238 .RS 22n
 239 configuration file for the name service switch
 240 .RE
 241
 242 .SH ATTRIBUTES
 243 .sp
 244 .LP
 245 See \fBattributes\fR(5) for descriptions of the following attributes:
 246 .sp
 247
 248 .sp
 249 .TS
 250 box;
 251 c | c
 252 l | l .
 253 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 254 _
 255 MT-Level        MT-Safe
 256 .TE
 257
 258 .SH SEE ALSO
 259 .sp
 260 .LP
 261 \fBIntro\fR(2), \fBIntro\fR(3), \fBbyteorder\fR(3SOCKET), \fBinet\fR(3SOCKET),
 262 \fBnetdb.h\fR(3HEAD), \fBnetworks\fR(4), \fBnsswitch.conf\fR(4),
 263 \fBattributes\fR(5)
 264 .sp
 265 .LP
 266 Fuller, V., Li, T., Yu, J., and Varadhan, K. \fIRFC 1519, Classless
 267 Inter-Domain Routing (CIDR): an Address Assignment and Aggregation Strategy\fR.
 268 Network Working Group. September 1993.
 269 .SH WARNINGS
 270 .sp
 271 .LP
 272 The reentrant interfaces \fBgetnetbyname_r()\fR, \fBgetnetbyaddr_r()\fR, and
 273 \fBgetnetent_r()\fR are included in this release on an uncommitted basis only,
 274 and are subject to change or removal in future minor releases.
 275 .SH NOTES
 276 .sp
 277 .LP
 278 The current implementation of these functions only return or accept network
 279 numbers for the Internet address family (type \fBAF_INET\fR). The functions
 280 described in \fBinet\fR(3SOCKET) may be helpful in constructing and
 281 manipulating addresses and network numbers in this form.
 282 .sp
 283 .LP
 284 When compiling multi-threaded applications, see \fBIntro\fR(3), \fINotes On
 285 Multithread Applications\fR, for information about the use of the
 286 \fB_REENTRANT\fR flag.
 287 .sp
 288 .LP
 289 Use of the enumeration interfaces \fBgetnetent()\fR and \fBgetnetent_r()\fR is
 290 discouraged; enumeration may not be supported for all database sources. The
 291 semantics of enumeration are discussed further in \fBnsswitch.conf\fR(4).