unified MX27, MX25, MX37 trees
[karo-tx-redboot.git] / packages / net / common / v2_0 / doc / tcpip-manpages.sgml
1 <!-- HEY YOU!!!!!!!!! -->
2 <!-- this file is automatically generated by the script -->
3 <!--       ./prepare-manpages.sh      -->
4 <!-- so PLEASE do not modify it: your changes will be lost -->
5
6
7 <chapter id="tcpip-library-reference">
8   <title>TCP/IP Library Reference</title>
9
10
11   <sect1 id="net-common-tcpip-manpages-getdomainname">
12     <title>getdomainname</title>
13     <screen>
14 GETDOMAINNAME(3)         BSD Library Functions Manual         GETDOMAINNAME(3)
15
16 NAME
17      getdomainname, setdomainname - get/set YP domain name of current host
18
19 SYNOPSIS
20      #include &lt;unistd.h>
21
22      int
23      getdomainname(char *name, size_t namelen);
24
25      int
26      setdomainname(const char *name, size_t namelen);
27
28 DESCRIPTION
29      The getdomainname() function returns the YP domain name for the current
30      processor, as previously set by setdomainname().  The parameter namelen
31      specifies the size of the name array.  If insufficient space is provided,
32      the returned name is truncated.  The returned name is always null termi-
33      nated.
34
35      setdomainname() sets the domain name of the host machine to be name,
36      which has length namelen.  This call is restricted to the superuser and
37      is normally used only when the system is bootstrapped.
38
39 RETURN VALUES
40      If the call succeeds a value of 0 is returned.  If the call fails, a
41      value of -1 is returned and an error code is placed in the global vari-
42      able errno.
43
44 ERRORS
45      The following errors may be returned by these calls:
46
47      [EFAULT]           The name or namelen parameter gave an invalid address.
48
49      [EPERM]            The caller tried to set the domain name and was not
50                         the superuser.
51
52 SEE ALSO
53      domainname(1), gethostid(3), gethostname(3), sysctl(3), sysctl(8), yp(8)
54
55 BUGS
56      Domain names are limited to MAXHOSTNAMELEN (from &lt;sys/param.h>) charac-
57      ters, currently 256.  This includes the terminating NUL character.
58
59      If the buffer passed to getdomainname() is too small, other operating
60      systems may not guarantee termination with NUL.
61
62 HISTORY
63      The getdomainname function call appeared in SunOS 3.x.
64
65 BSD                               May 6, 1994                              BSD
66     </screen>
67   </sect1>
68
69   <sect1 id="net-common-tcpip-manpages-gethostname">
70     <title>gethostname</title>
71     <screen>
72 GETHOSTNAME(3)           BSD Library Functions Manual           GETHOSTNAME(3)
73
74 NAME
75      gethostname, sethostname - get/set name of current host
76
77 SYNOPSIS
78      #include &lt;unistd.h>
79
80      int
81      gethostname(char *name, size_t namelen);
82
83      int
84      sethostname(const char *name, size_t namelen);
85
86 DESCRIPTION
87      The gethostname() function returns the standard host name for the current
88      processor, as previously set by sethostname().  The parameter namelen
89      specifies the size of the name array.  If insufficient space is provided,
90      the returned name is truncated.  The returned name is always null termi-
91      nated.
92
93      sethostname() sets the name of the host machine to be name, which has
94      length namelen.  This call is restricted to the superuser and is normally
95      used only when the system is bootstrapped.
96
97 RETURN VALUES
98      If the call succeeds a value of 0 is returned.  If the call fails, a
99      value of -1 is returned and an error code is placed in the global vari-
100      able errno.
101
102 ERRORS
103      The following errors may be returned by these calls:
104
105      [EFAULT]           The name or namelen parameter gave an invalid address.
106
107      [EPERM]            The caller tried to set the hostname and was not the
108                         superuser.
109
110 SEE ALSO
111      hostname(1), getdomainname(3), gethostid(3), sysctl(3), sysctl(8), yp(8)
112
113 STANDARDS
114      The gethostname() function call conforms to X/Open Portability Guide
115      Issue 4.2 (``XPG4.2'').
116
117 HISTORY
118      The gethostname() function call appeared in 4.2BSD.
119
120 BUGS
121      Host names are limited to MAXHOSTNAMELEN (from &lt;sys/param.h>) characters,
122      currently 256.  This includes the terminating NUL character.
123
124      If the buffer passed to gethostname() is smaller than MAXHOSTNAMELEN,
125      other operating systems may not guarantee termination with NUL.
126
127 BSD                              June 4, 1993                              BSD
128     </screen>
129   </sect1>
130
131   <sect1 id="net-common-tcpip-manpages-byteorder">
132     <title>byteorder</title>
133     <screen>
134 BYTEORDER(3)             BSD Library Functions Manual             BYTEORDER(3)
135
136 NAME
137      htonl, htons, ntohl, ntohs, htobe32, htobe16, betoh32, betoh16, htole32,
138      htole16, letoh32, letoh16, swap32, swap16 - convert values between dif-
139      ferent byte orderings
140
141 SYNOPSIS
142      #include &lt;sys/types.h>
143      #include &lt;machine/endian.h>
144
145      u_int32_t
146      htonl(u_int32_t host32);
147
148      u_int16_t
149      htons(u_int16_t host16);
150
151      u_int32_t
152      ntohl(u_int32_t net32);
153
154      u_int16_t
155      ntohs(u_int16_t net16);
156
157      u_int32_t
158      htobe32(u_int32_t host32);
159
160      u_int16_t
161      htobe16(u_int16_t host16);
162
163      u_int32_t
164      betoh32(u_int32_t big32);
165
166      u_int16_t
167      betoh16(u_int16_t big16);
168
169      u_int32_t
170      htole32(u_int32_t host32);
171
172      u_int16_t
173      htole16(u_int16_t host16);
174
175      u_int32_t
176      letoh32(u_int32_t little32);
177
178      u_int16_t
179      letoh16(u_int16_t little16);
180
181      u_int32_t
182      swap32(u_int32_t val32);
183
184      u_int16_t
185      swap16(u_int16_t val16);
186
187 DESCRIPTION
188      These routines convert 16- and 32-bit quantities between different byte
189      orderings.  The ``swap'' functions reverse the byte ordering of the given
190      quantity, the others converts either from/to the native byte order used
191      by the host to/from either little- or big-endian (a.k.a network) order.
192
193      Apart from the swap functions, the names can be described by this form:
194      {src-order}to{dst-order}{size}.  Both {src-order} and {dst-order} can
195      take the following forms:
196
197            h    Host order.
198            n    Network order (big-endian).
199            be   Big-endian (most significant byte first).
200            le   Little-endian (least significant byte first).
201
202      One of the specified orderings must be 'h'.  {size} will take these
203      forms:
204
205            l  Long (32-bit, used in conjunction with forms involving 'n').
206            s  Short (16-bit, used in conjunction with forms involving 'n').
207            16
208               16-bit.
209            32
210               32-bit.
211
212      The swap functions are of the form: swap{size}.
213
214      Names involving 'n' convert quantities between network byte order and
215      host byte order.  The last letter ('s' or 'l') is a mnemonic for the tra-
216      ditional names for such quantities, short and long, respectively.  Today,
217      the C concept of short and long integers need not coincide with this tra-
218      ditional misunderstanding.  On machines which have a byte order which is
219      the same as the network order, routines are defined as null macros.
220
221      The functions involving either ``be'', ``le'', or ``swap'' use the num-
222      bers 16 and 32 for specifying the bitwidth of the quantities they operate
223      on.  Currently all supported architectures are either big- or little-
224      endian so either the ``be'' or ``le'' variants are implemented as null
225      macros.
226
227      The routines mentioned above which have either {src-order} or {dst-order}
228      set to 'n' are most often used in conjunction with Internet addresses and
229      ports as returned by gethostbyname(3) and getservent(3).
230
231 SEE ALSO
232      gethostbyname(3), getservent(3)
233
234 HISTORY
235      The byteorder functions appeared in 4.2BSD.
236
237 BUGS
238      On the vax, alpha, i386, and so far mips, bytes are handled backwards
239      from most everyone else in the world.  This is not expected to be fixed
240      in the near future.
241
242 BSD                              June 4, 1993                              BSD
243     </screen>
244   </sect1>
245
246   <sect1 id="net-common-tcpip-manpages-ethers">
247     <title>ethers</title>
248     <screen>
249 ETHERS(3)                BSD Library Functions Manual                ETHERS(3)
250
251 NAME
252      ether_aton, ether_ntoa, ether_addr, ether_ntohost, ether_hostton,
253      ether_line - get ethers entry
254
255 SYNOPSIS
256      #include &lt;netinet/if_ether.h>
257
258      char *
259      ether_ntoa(struct ether_addr *e);
260
261      struct ether_addr *
262      ether_aton(char *s);
263
264      int
265      ether_ntohost(char *hostname, struct ether_addr *e);
266
267      int
268      ether_hostton(char *hostname, struct ether_addr *e);
269
270      int
271      ether_line(char *l, struct ether_addr *e, char *hostname);
272
273 DESCRIPTION
274      Ethernet addresses are represented by the following structure:
275
276            struct ether_addr {
277                    u_int8_t  ether_addr_octet[6];
278            };
279
280      The ether_ntoa() function converts this structure into an ASCII string of
281      the form ``xx:xx:xx:xx:xx:xx'', consisting of 6 hexadecimal numbers sepa-
282      rated by colons.  It returns a pointer to a static buffer that is reused
283      for each call.  The ether_aton() converts an ASCII string of the same
284      form and to a structure containing the 6 octets of the address.  It
285      returns a pointer to a static structure that is reused for each call.
286
287      The ether_ntohost() and ether_hostton() functions interrogate the
288      database mapping host names to Ethernet addresses, /etc/ethers.  The
289      ether_ntohost() function looks up the given Ethernet address and writes
290      the associated host name into the character buffer passed.  This buffer
291      should be MAXHOSTNAMELEN characters in size.  The ether_hostton() func-
292      tion looks up the given host name and writes the associated Ethernet
293      address into the structure passed.  Both functions return zero if they
294      find the requested host name or address, and -1 if not.
295
296      Each call reads /etc/ethers from the beginning; if a '+' appears alone on
297      a line in the file, then ether_hostton() will consult the ethers.byname
298      YP map, and ether_ntohost() will consult the ethers.byaddr YP map.
299
300      The ether_line() function parses a line from the /etc/ethers file and
301      fills in the passed struct ether_addr and character buffer with the Eth-
302      ernet address and host name on the line.  It returns zero if the line was
303      successfully parsed and -1 if not.  The character buffer should be
304      MAXHOSTNAMELEN characters in size.
305
306 FILES
307      /etc/ethers
308
309 SEE ALSO
310      ethers(5)
311
312 HISTORY
313      The ether_ntoa(), ether_aton(), ether_ntohost(), ether_hostton(), and
314      ether_line() functions were adopted from SunOS and appeared in NetBSD 0.9
315      b.
316
317 BUGS
318      The data space used by these functions is static; if future use requires
319      the data, it should be copied before any subsequent calls to these func-
320      tions overwrite it.
321
322 BSD                            December 16, 1993                           BSD
323     </screen>
324   </sect1>
325
326   <sect1 id="net-common-tcpip-manpages-getaddrinfo">
327     <title>getaddrinfo</title>
328     <screen>
329 GETADDRINFO(3)           BSD Library Functions Manual           GETADDRINFO(3)
330
331 NAME
332      getaddrinfo, freeaddrinfo, gai_strerror - nodename-to-address translation
333      in protocol-independent manner
334
335 SYNOPSIS
336      #include &lt;sys/types.h>
337      #include &lt;sys/socket.h>
338      #include &lt;netdb.h>
339
340      int
341      getaddrinfo(const char *nodename, const char *servname,
342              const struct addrinfo *hints, struct addrinfo **res);
343
344      void
345      freeaddrinfo(struct addrinfo *ai);
346
347      char *
348      gai_strerror(int ecode);
349
350 DESCRIPTION
351      The getaddrinfo() function is defined for protocol-independent nodename-
352      to-address translation.  It performs the functionality of
353      gethostbyname(3) and getservbyname(3), but in a more sophisticated man-
354      ner.
355
356      The addrinfo structure is defined as a result of including the &lt;netdb.h>
357      header:
358
359      struct addrinfo {                                                  *
360           int     ai_flags;     /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
361           int     ai_family;    /* PF_xxx */
362           int     ai_socktype;  /* SOCK_xxx */
363           int     ai_protocol;  /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
364           size_t  ai_addrlen;   /* length of ai_addr */
365           char   *ai_canonname; /* canonical name for nodename */
366           struct sockaddr  *ai_addr; /* binary address */
367           struct addrinfo  *ai_next; /* next structure in linked list */
368      };
369
370      The nodename and servname arguments are pointers to NUL-terminated
371      strings or NULL.  One or both of these two arguments must be a non-null
372      pointer.  In the normal client scenario, both the nodename and servname
373      are specified.  In the normal server scenario, only the servname is spec-
374      ified.  A non-null nodename string can be either a node name or a numeric
375      host address string (i.e., a dotted-decimal IPv4 address or an IPv6 hex
376      address).  A non-null servname string can be either a service name or a
377      decimal port number.
378
379      The caller can optionally pass an addrinfo structure, pointed to by the
380      third argument, to provide hints concerning the type of socket that the
381      caller supports.  In this hints structure all members other than
382      ai_flags, ai_family, ai_socktype, and ai_protocol must be zero or a null
383      pointer.  A value of PF_UNSPEC for ai_family means the caller will accept
384      any protocol family.  A value of 0 for ai_socktype means the caller will
385      accept any socket type.  A value of 0 for ai_protocol means the caller
386      will accept any protocol.  For example, if the caller handles only TCP
387      and not UDP, then the ai_socktype member of the hints structure should be
388      set to SOCK_STREAM when getaddrinfo() is called.  If the caller handles
389      only IPv4 and not IPv6, then the ai_family member of the hints structure
390      should be set to PF_INET when getaddrinfo() is called.  If the third
391      argument to getaddrinfo() is a null pointer, this is the same as if the
392      caller had filled in an addrinfo structure initialized to zero with
393      ai_family set to PF_UNSPEC.
394
395      Upon successful return a pointer to a linked list of one or more addrinfo
396      structures is returned through the final argument.  The caller can pro-
397      cess each addrinfo structure in this list by following the ai_next
398      pointer, until a null pointer is encountered.  In each returned addrinfo
399      structure the three members ai_family, ai_socktype, and ai_protocol are
400      the corresponding arguments for a call to the socket() function.  In each
401      addrinfo structure the ai_addr member points to a filled-in socket
402      address structure whose length is specified by the ai_addrlen member.
403
404      If the AI_PASSIVE bit is set in the ai_flags member of the hints struc-
405      ture, then the caller plans to use the returned socket address structure
406      in a call to bind().  In this case, if the nodename argument is a null
407      pointer, then the IP address portion of the socket address structure will
408      be set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6
409      address.
410
411      If the AI_PASSIVE bit is not set in the ai_flags member of the hints
412      structure, then the returned socket address structure will be ready for a
413      call to connect() (for a connection-oriented protocol) or either
414      connect(), sendto(), or sendmsg() (for a connectionless protocol).  In
415      this case, if the nodename argument is a null pointer, then the IP
416      address portion of the socket address structure will be set to the loop-
417      back address.
418
419      If the AI_CANONNAME bit is set in the ai_flags member of the hints struc-
420      ture, then upon successful return the ai_canonname member of the first
421      addrinfo structure in the linked list will point to a NUL-terminated
422      string containing the canonical name of the specified nodename.
423
424      If the AI_NUMERICHOST bit is set in the ai_flags member of the hints
425      structure, then a non-null nodename string must be a numeric host address
426      string.  Otherwise an error of EAI_NONAME is returned.  This flag pre-
427      vents any type of name resolution service (e.g., the DNS) from being
428      called.
429
430      The arguments to getaddrinfo() must sufficiently be consistent and unam-
431      biguous.  Here are pitfall cases you may encounter:
432
433      o   getaddrinfo() will raise an error if members of the hints structure
434          are not consistent.  For example, for internet address families,
435          getaddrinfo() will raise an error if you specify SOCK_STREAM to
436          ai_socktype while you specify IPPROTO_UDP to ai_protocol.
437
438      o   If you specify a servname which is defined only for certain
439          ai_socktype, getaddrinfo() will raise an error because the arguments
440          are not consistent.  For example, getaddrinfo() will raise an error
441          if you ask for ``tftp'' service on SOCK_STREAM.
442
443      o   For internet address families, if you specify servname while you set
444          ai_socktype to SOCK_RAW, getaddrinfo() will raise an error, because
445          service names are not defined for the internet SOCK_RAW space.
446
447      o   If you specify a numeric servname, while leaving ai_socktype and
448          ai_protocol unspecified, getaddrinfo() will raise an error.  This is
449          because the numeric servname does not identify any socket type, and
450          getaddrinfo() is not allowed to glob the argument in such case.
451
452      All of the information returned by getaddrinfo() is dynamically allo-
453      cated: the addrinfo structures, the socket address structures, and canon-
454      ical node name strings pointed to by the addrinfo structures.  To return
455      this information to the system the function freeaddrinfo() is called.
456      The addrinfo structure pointed to by the ai argument is freed, along with
457      any dynamic storage pointed to by the structure.  This operation is
458      repeated until a NULL ai_next pointer is encountered.
459
460      To aid applications in printing error messages based on the EAI_xxx codes
461      returned by getaddrinfo(), gai_strerror() is defined.  The argument is
462      one of the EAI_xxx values defined earlier and the return value points to
463      a string describing the error.  If the argument is not one of the EAI_xxx
464      values, the function still returns a pointer to a string whose contents
465      indicate an unknown error.
466
467    Extension for scoped IPv6 address
468      The implementation allows experimental numeric IPv6 address notation with
469      scope identifier.  By appending the percent character and scope identi-
470      fier to addresses, you can fill sin6_scope_id field for addresses.  This
471      would make management of scoped address easier, and allows cut-and-paste
472      input of scoped address.
473
474      At this moment the code supports only link-local addresses with the for-
475      mat.  Scope identifier is hardcoded to name of hardware interface associ-
476      ated with the link.  (such as ne0).  Example would be like
477      ``fe80::1%ne0'', which means ``fe80::1 on the link associated with ne0
478      interface''.
479
480      The implementation is still very experimental and non-standard.  The cur-
481      rent implementation assumes one-by-one relationship between interface and
482      link, which is not necessarily true from the specification.
483
484 EXAMPLES
485      The following code tries to connect to ``www.kame.net'' service ``http''.
486      via stream socket.  It loops through all the addresses available, regard-
487      less from address family.  If the destination resolves to IPv4 address,
488      it will use AF_INET socket.  Similarly, if it resolves to IPv6, AF_INET6
489      socket is used.  Observe that there is no hardcoded reference to particu-
490      lar address family.  The code works even if getaddrinfo returns addresses
491      that are not IPv4/v6.
492
493            struct addrinfo hints, *res, *res0;
494            int error;
495            int s;
496            const char *cause = NULL;
497
498            memset(&amp;hints, 0, sizeof(hints));
499            hints.ai_family = PF_UNSPEC;
500            hints.ai_socktype = SOCK_STREAM;
501            error = getaddrinfo("www.kame.net", "http", &amp;hints, &amp;res0);
502            if (error) {
503                    errx(1, "%s", gai_strerror(error));
504                    /*NOTREACHED*/
505            }
506            s = -1;
507            for (res = res0; res; res = res->ai_next) {
508                    s = socket(res->ai_family, res->ai_socktype,
509                        res->ai_protocol);
510                    if (s &lt; 0) {
511                            cause = "socket";
512                            continue;
513                    }
514
515                    if (connect(s, res->ai_addr, res->ai_addrlen) &lt; 0) {
516                            cause = "connect";
517                            close(s);
518                            s = -1;
519                            continue;
520                    }
521
522                    break;  /* okay we got one */
523            }
524            if (s &lt; 0) {
525                    err(1, cause);
526                    /*NOTREACHED*/
527            }
528            freeaddrinfo(res0);
529
530      The following example tries to open a wildcard listening socket onto ser-
531      vice ``http'', for all the address families available.
532
533            struct addrinfo hints, *res, *res0;
534            int error;
535            int s[MAXSOCK];
536            int nsock;
537            const char *cause = NULL;
538
539            memset(&amp;hints, 0, sizeof(hints));
540            hints.ai_family = PF_UNSPEC;
541            hints.ai_socktype = SOCK_STREAM;
542            hints.ai_flags = AI_PASSIVE;
543            error = getaddrinfo(NULL, "http", &amp;hints, &amp;res0);
544            if (error) {
545                    errx(1, "%s", gai_strerror(error));
546                    /*NOTREACHED*/
547            }
548            nsock = 0;
549            for (res = res0; res &amp;&amp; nsock &lt; MAXSOCK; res = res->ai_next) {
550                    s[nsock] = socket(res->ai_family, res->ai_socktype,
551                        res->ai_protocol);
552                    if (s[nsock] &lt; 0) {
553                            cause = "socket";
554                            continue;
555                    }
556
557                    if (bind(s[nsock], res->ai_addr, res->ai_addrlen) &lt; 0) {
558                            cause = "bind";
559                            close(s[nsock]);
560                            continue;
561                    }
562                    (void) listen(s[nsock], 5);
563
564                    nsock++;
565            }
566            if (nsock == 0) {
567                    err(1, cause);
568                    /*NOTREACHED*/
569            }
570            freeaddrinfo(res0);
571
572 DIAGNOSTICS
573      Error return status from getaddrinfo() is zero on success and non-zero on
574      errors.  Non-zero error codes are defined in &lt;netdb.h>, and as follows:
575
576      EAI_ADDRFAMILY  Address family for nodename not supported.
577      EAI_AGAIN       Temporary failure in name resolution.
578      EAI_BADFLAGS    Invalid value for ai_flags.
579      EAI_FAIL        Non-recoverable failure in name resolution.
580      EAI_FAMILY      ai_family not supported.
581      EAI_MEMORY      Memory allocation failure.
582      EAI_NODATA      No address associated with nodename.
583      EAI_NONAME      nodename nor servname provided, or not known.
584      EAI_SERVICE     servname not supported for ai_socktype.
585      EAI_SOCKTYPE    ai_socktype not supported.
586      EAI_SYSTEM      System error returned in errno.
587
588      If called with proper argument, gai_strerror() returns a pointer to a
589      string describing the given error code.  If the argument is not one of
590      the EAI_xxx values, the function still returns a pointer to a string
591      whose contents indicate an unknown error.
592
593 SEE ALSO
594      getnameinfo(3), gethostbyname(3), getservbyname(3), hosts(5),
595      resolv.conf(5), services(5), hostname(7), named(8)
596
597      R. Gilligan, S. Thomson, J. Bound, and W. Stevens, Basic Socket Interface
598      Extensions for IPv6, RFC2553, March 1999.
599
600      Tatsuya Jinmei and Atsushi Onoe, An Extension of Format for IPv6 Scoped
601      Addresses, internet draft, draft-ietf-ipngwg-scopedaddr-format-02.txt,
602      work in progress material.
603
604      Craig Metz, "Protocol Independence Using the Sockets API", Proceedings of
605      the freenix track: 2000 USENIX annual technical conference, June 2000.
606
607 HISTORY
608      The implementation first appeared in WIDE Hydrangea IPv6 protocol stack
609      kit.
610
611 STANDARDS
612      The getaddrinfo() function is defined in IEEE POSIX 1003.1g draft speci-
613      fication, and documented in ``Basic Socket Interface Extensions for
614      IPv6'' (RFC2553).
615
616 BUGS
617      The current implementation is not thread-safe.
618
619      The text was shamelessly copied from RFC2553.
620
621 BSD                              May 25, 1995                              BSD
622     </screen>
623   </sect1>
624
625   <sect1 id="net-common-tcpip-manpages-gethostbyname">
626     <title>gethostbyname</title>
627     <screen>
628 GETHOSTBYNAME(3)         BSD Library Functions Manual         GETHOSTBYNAME(3)
629
630 NAME
631      gethostbyname, gethostbyname2, gethostbyaddr, gethostent, sethostent,
632      endhostent, hstrerror, herror - get network host entry
633
634 SYNOPSIS
635      #include &lt;netdb.h>
636      extern int h_errno;
637
638      struct hostent *
639      gethostbyname(const char *name);
640
641      struct hostent *
642      gethostbyname2(const char *name, int af);
643
644      struct hostent *
645      gethostbyaddr(const char *addr, int len, int af);
646
647      struct hostent *
648      gethostent(void);
649
650      void
651      sethostent(int stayopen);
652
653      void
654      endhostent(void);
655
656      void
657      herror(const char *string);
658
659      const char *
660      hstrerror(int err);
661
662 DESCRIPTION
663      The gethostbyname() and gethostbyaddr() functions each return a pointer
664      to an object with the following structure describing an internet host
665      referenced by name or by address, respectively.  This structure contains
666      either information obtained from the name server (i.e., resolver(3) and
667      named(8)), broken-out fields from a line in /etc/hosts, or database
668      entries supplied by the yp(8) system.  resolv.conf(5) describes how the
669      particular database is chosen.
670
671      struct  hostent {
672              char    *h_name;        /* official name of host */
673              char    **h_aliases;    /* alias list */
674              int     h_addrtype;     /* host address type */
675              int     h_length;       /* length of address */
676              char    **h_addr_list;  /* list of addresses from name server */
677      };
678      #define h_addr  h_addr_list[0]  /* address, for backward compatibility */
679
680      The members of this structure are:
681
682      h_name       Official name of the host.
683
684      h_aliases    A zero-terminated array of alternate names for the host.
685
686      h_addrtype   The type of address being returned.
687
688      h_length     The length, in bytes, of the address.
689
690      h_addr_list  A zero-terminated array of network addresses for the host.
691                   Host addresses are returned in network byte order.
692
693      h_addr       The first address in h_addr_list; this is for backward com-
694                   patibility.
695
696      The function gethostbyname() will search for the named host in the cur-
697      rent domain and its parents using the search lookup semantics detailed in
698      resolv.conf(5) and hostname(7).
699
700      gethostbyname2() is an advanced form of gethostbyname() which allows
701      lookups in address families other than AF_INET, for example AF_INET6.
702
703      The gethostbyaddr() function will search for the specified address of
704      length len in the address family af.  The only address family currently
705      supported is AF_INET.
706
707      The sethostent() function may be used to request the use of a connected
708      TCP socket for queries.  If the stayopen flag is non-zero, this sets the
709      option to send all queries to the name server using TCP and to retain the
710      connection after each call to gethostbyname() or gethostbyaddr().  Other-
711      wise, queries are performed using UDP datagrams.
712
713      The endhostent() function closes the TCP connection.
714
715      The herror() function prints an error message describing the failure.  If
716      its argument string is non-null, it is prepended to the message string
717      and separated from it by a colon (':') and a space.  The error message is
718      printed with a trailing newline.  The contents of the error message is
719      the same as that returned by hstrerror() with argument h_errno.
720
721 FILES
722      /etc/hosts
723      /etc/resolv.conf
724
725 DIAGNOSTICS
726      Error return status from gethostbyname(), gethostbyname2(), and
727      gethostbyaddr() is indicated by return of a null pointer.  The external
728      integer h_errno may then be checked to see whether this is a temporary
729      failure or an invalid or unknown host.
730
731      The variable h_errno can have the following values:
732
733      HOST_NOT_FOUND  No such host is known.
734
735      TRY_AGAIN       This is usually a temporary error and means that the
736                      local server did not receive a response from an authori-
737                      tative server.  A retry at some later time may succeed.
738
739      NO_RECOVERY     Some unexpected server failure was encountered.  This is
740                      a non-recoverable error.
741
742      NO_DATA         The requested name is valid but does not have an IP
743                      address; this is not a temporary error.  This means that
744                      the name is known to the name server but there is no
745                      address associated with this name.  Another type of
746                      request to the name server using this domain name will
747                      result in an answer; for example, a mail-forwarder may be
748                      registered for this domain.
749
750 SEE ALSO
751      resolver(3), getaddrinfo(3), getnameinfo(3), hosts(5), resolv.conf(5),
752      hostname(7), named(8)
753
754 CAVEAT
755      If the search routines in resolv.conf(5) decide to read the /etc/hosts
756      file, gethostent() and other functions will read the next line of the
757      file, re-opening the file if necessary.
758
759      The sethostent() function opens and/or rewinds the file /etc/hosts.  If
760      the stayopen argument is non-zero, the file will not be closed after each
761      call to gethostbyname(), gethostbyname2(), or gethostbyaddr().
762
763      The endhostent() function closes the file.
764
765 HISTORY
766      The herror() function appeared in 4.3BSD.  The endhostent(),
767      gethostbyaddr(), gethostbyname(), gethostent(), and sethostent() func-
768      tions appeared in 4.2BSD.
769
770 BUGS
771      These functions use static data storage; if the data is needed for future
772      use, it should be copied before any subsequent calls overwrite it.  Only
773      the Internet address formats are currently understood.
774
775      YP does not support any address families other than AF_INET and uses the
776      traditional database format.
777
778 BSD                             March 13, 1997                             BSD
779     </screen>
780   </sect1>
781
782   <sect1 id="net-common-tcpip-manpages-getifaddrs">
783     <title>getifaddrs</title>
784     <screen>
785 GETIFADDRS(3)            BSD Library Functions Manual            GETIFADDRS(3)
786
787 NAME
788      getifaddrs - get interface addresses
789
790 SYNOPSIS
791      #include &lt;sys/types.h>
792      #include &lt;sys/socket.h>
793      #include &lt;ifaddrs.h>
794
795      int
796      getifaddrs(struct ifaddrs **ifap);
797
798      void
799      freeifaddrs(struct ifaddrs *ifap);
800
801 DESCRIPTION
802      The getifaddrs() function stores a reference to a linked list of the net-
803      work interfaces on the local machine in the memory referenced by ifap.
804      The list consists of ifaddrs structures, as defined in the include file
805      &lt;ifaddrs.h>.  The ifaddrs structure contains at least the following
806      entries:
807
808          struct ifaddrs   *ifa_next;         /* Pointer to next struct */
809          char             *ifa_name;         /* Interface name */
810          u_int             ifa_flags;        /* Interface flags */
811          struct sockaddr  *ifa_addr;         /* Interface address */
812          struct sockaddr  *ifa_netmask;      /* Interface netmask */
813          struct sockaddr  *ifa_broadaddr;    /* Interface broadcast address */
814          struct sockaddr  *ifa_dstaddr;      /* P2P interface destination */
815          void             *ifa_data;         /* Address specific data */
816
817      ifa_next
818              Contains a pointer to the next structure on the list.  This field
819              is set to NULL in last structure on the list.
820
821      ifa_name
822              Contains the interface name.
823
824      ifa_flags
825              Contains the interface flags, as set by ifconfig(8).
826
827      ifa_addr
828              References either the address of the interface or the link level
829              address of the interface, if one exists, otherwise it is NULL.
830              (The sa_family field of the ifa_addr field should be consulted to
831              determine the format of the ifa_addr address.)
832
833      ifa_netmask
834              References the netmask associated with ifa_addr, if one is set,
835              otherwise it is NULL.
836
837      ifa_broadaddr
838              This field, which should only be referenced for non-P2P inter-
839              faces, references the broadcast address associated with ifa_addr,
840              if one exists, otherwise it is NULL.
841
842      ifa_dstaddr
843              References the destination address on a P2P interface, if one
844              exists, otherwise it is NULL.
845
846      ifa_data
847              References address family specific data.  For AF_LINK addresses
848              it contains a pointer to the struct if_data (as defined in
849              include file &lt;net/if.h>) which contains various interface
850              attributes and statistics.  For all other address families, it
851              contains a pointer to the struct ifa_data (as defined in include
852              file &lt;net/if.h>) which contains per-address interface statistics.
853
854      The data returned by getifaddrs() is dynamically allocated and should be
855      freed using freeifaddrs() when no longer needed.
856
857 RETURN VALUES
858      Upon successful completion, a value of 0 is returned.  Otherwise, a value
859      of -1 is returned and errno is set to indicate the error.
860
861 ERRORS
862      The getifaddrs() may fail and set errno for any of the errors specified
863      for the library routines ioctl(2), socket(2), malloc(3), or sysctl(3).
864
865 BUGS
866      If both &lt;net/if.h> and &lt;ifaddrs.h> are being included, &lt;net/if.h> must be
867      included before &lt;ifaddrs.h>.
868
869 SEE ALSO
870      ioctl(2), socket(2), sysctl(3), networking(4), ifconfig(8)
871
872 HISTORY
873      The getifaddrs() function first appeared in BSDI BSD/OS.  The function is
874      supplied on OpenBSD since OpenBSD 2.7.
875
876 BSD                            October 13, 2005                            BSD
877     </screen>
878   </sect1>
879
880   <sect1 id="net-common-tcpip-manpages-getnameinfo">
881     <title>getnameinfo</title>
882     <screen>
883 GETNAMEINFO(3)           BSD Library Functions Manual           GETNAMEINFO(3)
884
885 NAME
886      getnameinfo - address-to-nodename translation in protocol-independent
887      manner
888
889 SYNOPSIS
890      #include &lt;sys/types.h>
891      #include &lt;sys/socket.h>
892      #include &lt;netdb.h>
893
894      int
895      getnameinfo(const struct sockaddr *sa, socklen_t salen, char *host,
896              size_t hostlen, char *serv, size_t servlen, int flags);
897
898 DESCRIPTION
899      The getnameinfo() function is defined for protocol-independent address-
900      to-nodename translation.  Its functionality is a reverse conversion of
901      getaddrinfo(3), and implements similar functionality with
902      gethostbyaddr(3) and getservbyport(3) in more sophisticated manner.
903
904      This function looks up an IP address and port number provided by the
905      caller in the DNS and system-specific database, and returns text strings
906      for both in buffers provided by the caller.  The function indicates suc-
907      cessful completion by a zero return value; a non-zero return value indi-
908      cates failure.
909
910      The first argument, sa, points to either a sockaddr_in structure (for
911      IPv4) or a sockaddr_in6 structure (for IPv6) that holds the IP address
912      and port number.  The salen argument gives the length of the sockaddr_in
913      or sockaddr_in6 structure.
914
915      The function returns the nodename associated with the IP address in the
916      buffer pointed to by the host argument.  The caller provides the size of
917      this buffer via the hostlen argument.  The service name associated with
918      the port number is returned in the buffer pointed to by serv, and the
919      servlen argument gives the length of this buffer.  The caller specifies
920      not to return either string by providing a zero value for the hostlen or
921      servlen arguments.  Otherwise, the caller must provide buffers large
922      enough to hold the nodename and the service name, including the terminat-
923      ing null characters.
924
925      Unfortunately most systems do not provide constants that specify the max-
926      imum size of either a fully-qualified domain name or a service name.
927      Therefore to aid the application in allocating buffers for these two
928      returned strings the following constants are defined in &lt;netdb.h>:
929
930      #define NI_MAXHOST    MAXHOSTNAMELEN
931      #define NI_MAXSERV    32
932
933      The first value is actually defined as the constant MAXDNAME in recent
934      versions of BIND's &lt;arpa/nameser.h> header (older versions of BIND define
935      this constant to be 256) and the second is a guess based on the services
936      listed in the current Assigned Numbers RFC.
937
938      The final argument is a flag that changes the default actions of this
939      function.  By default the fully-qualified domain name (FQDN) for the host
940      is looked up in the DNS and returned.  If the flag bit NI_NOFQDN is set,
941      only the nodename portion of the FQDN is returned for local hosts.
942
943      If the flag bit NI_NUMERICHOST is set, or if the host's name cannot be
944      located in the DNS, the numeric form of the host's address is returned
945      instead of its name (e.g., by calling inet_ntop() instead of
946      gethostbyaddr()).  If the flag bit NI_NAMEREQD is set, an error is
947      returned if the host's name cannot be located in the DNS.
948
949      If the flag bit NI_NUMERICSERV is set, the numeric form of the service
950      address is returned (e.g., its port number) instead of its name.  The two
951      NI_NUMERICxxx flags are required to support the -n flag that many com-
952      mands provide.
953
954      A fifth flag bit, NI_DGRAM, specifies that the service is a datagram ser-
955      vice, and causes getservbyport() to be called with a second argument of
956      "udp" instead of its default of "tcp".  This is required for the few
957      ports (512-514) that have different services for UDP and TCP.
958
959      These NI_xxx flags are defined in &lt;netdb.h>.
960
961    Extension for scoped IPv6 address
962      The implementation allows experimental numeric IPv6 address notation with
963      scope identifier.  IPv6 link-local address will appear as string like
964      ``fe80::1%ne0'', if NI_WITHSCOPEID bit is enabled in flags argument.
965      Refer to getaddrinfo(3) for the notation.
966
967 EXAMPLES
968      The following code tries to get numeric hostname, and service name, for
969      given socket address.  Observe that there is no hardcoded reference to
970      particular address family.
971
972            struct sockaddr *sa;    /* input */
973            char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
974
975            if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
976                sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) {
977                    errx(1, "could not get numeric hostname");
978                    /*NOTREACHED*/
979            }
980            printf("host=%s, serv=%s\n", hbuf, sbuf);
981
982      The following version checks if the socket address has reverse address
983      mapping.
984
985            struct sockaddr *sa;    /* input */
986            char hbuf[NI_MAXHOST];
987
988            if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
989                NI_NAMEREQD)) {
990                    errx(1, "could not resolve hostname");
991                    /*NOTREACHED*/
992            }
993            printf("host=%s\n", hbuf);
994
995 DIAGNOSTICS
996      The function indicates successful completion by a zero return value; a
997      non-zero return value indicates failure.  Error codes are as below:
998
999      EAI_AGAIN          The name could not be resolved at this time.  Future
1000                         attempts may succeed.
1001
1002      EAI_BADFLAGS       The flags had an invalid value.
1003
1004      EAI_FAIL           A non-recoverable error occurred.
1005
1006      EAI_FAMILY         The address family was not recognized or the address
1007                         length was invalid for the specified family.
1008
1009      EAI_MEMORY         There was a memory allocation failure.
1010
1011      EAI_NONAME         The name does not resolve for the supplied parameters.
1012                         NI_NAMEREQD is set and the host's name cannot be
1013                         located, or both nodename and servname were null.
1014
1015      EAI_SYSTEM         A system error occurred.  The error code can be found
1016                         in errno.
1017
1018 SEE ALSO
1019      getaddrinfo(3), gethostbyaddr(3), getservbyport(3), hosts(5),
1020      resolv.conf(5), services(5), hostname(7), named(8)
1021
1022      R. Gilligan, S. Thomson, J. Bound, and W. Stevens, Basic Socket Interface
1023      Extensions for IPv6, RFC2553, March 1999.
1024
1025      Tatsuya Jinmei and Atsushi Onoe, An Extension of Format for IPv6 Scoped
1026      Addresses, internet draft, draft-ietf-ipngwg-scopedaddr-format-02.txt,
1027      work in progress material.
1028
1029      Craig Metz, "Protocol Independence Using the Sockets API", Proceedings of
1030      the freenix track: 2000 USENIX annual technical conference, June 2000.
1031
1032 HISTORY
1033      The implementation first appeared in WIDE Hydrangea IPv6 protocol stack
1034      kit.
1035
1036 STANDARDS
1037      The getaddrinfo() function is defined IEEE POSIX 1003.1g draft specifica-
1038      tion, and documented in ``Basic Socket Interface Extensions for IPv6''
1039      (RFC2553).
1040
1041 BUGS
1042      The current implementation is not thread-safe.
1043
1044      The text was shamelessly copied from RFC2553.
1045
1046      OpenBSD intentionally uses different NI_MAXHOST value from what RFC2553
1047      suggests, to avoid buffer length handling mistakes.
1048
1049 BSD                              May 25, 1995                              BSD
1050     </screen>
1051   </sect1>
1052
1053   <sect1 id="net-common-tcpip-manpages-getnetent">
1054     <title>getnetent</title>
1055     <screen>
1056 GETNETENT(3)             BSD Library Functions Manual             GETNETENT(3)
1057
1058 NAME
1059      getnetent, getnetbyaddr, getnetbyname, setnetent, endnetent - get network
1060      entry
1061
1062 SYNOPSIS
1063      #include &lt;netdb.h>
1064
1065      struct netent *
1066      getnetent(void);
1067
1068      struct netent *
1069      getnetbyname(char *name);
1070
1071      struct netent *
1072      getnetbyaddr(in_addr_t net, int type);
1073
1074      void
1075      setnetent(int stayopen);
1076
1077      void
1078      endnetent(void);
1079
1080 DESCRIPTION
1081      The getnetent(), getnetbyname(), and getnetbyaddr() functions each return
1082      a pointer to an object with the following structure containing the bro-
1083      ken-out fields of a line in the network database, /etc/networks.
1084
1085            struct  netent {
1086                    char            *n_name;        /* official name of net */
1087                    char            **n_aliases;    /* alias list */
1088                    int             n_addrtype;     /* net number type */
1089                    in_addr_t       n_net;          /* net number */
1090            };
1091
1092      The members of this structure are:
1093
1094      n_name      The official name of the network.
1095
1096      n_aliases   A zero-terminated list of alternate names for the network.
1097
1098      n_addrtype  The type of the network number returned; currently only
1099                  AF_INET.
1100
1101      n_net       The network number.  Network numbers are returned in machine
1102                  byte order.
1103
1104      The getnetent() function reads the next line of the file, opening the
1105      file if necessary.
1106
1107      The setnetent() function opens and rewinds the file.  If the stayopen
1108      flag is non-zero, the net database will not be closed after each call to
1109      getnetbyname() or getnetbyaddr().
1110
1111      The endnetent() function closes the file.
1112
1113      The getnetbyname() and getnetbyaddr() functions search the domain name
1114      server if the system is configured to use one.  If the search fails, or
1115      no name server is configured, they sequentially search from the beginning
1116      of the file until a matching net name or net address and type is found,
1117      or until EOF is encountered.  Network numbers are supplied in host order.
1118
1119 FILES
1120      /etc/networks
1121
1122 DIAGNOSTICS
1123      Null pointer (0) returned on EOF or error.
1124
1125 SEE ALSO
1126      resolver(3), networks(5)
1127
1128 HISTORY
1129      The getnetent(), getnetbyaddr(), getnetbyname(), setnetent(), and
1130      endnetent() functions appeared in 4.2BSD.
1131
1132 BUGS
1133      The data space used by these functions is static; if future use requires
1134      the data, it should be copied before any subsequent calls to these func-
1135      tions overwrite it.  Only Internet network numbers are currently under-
1136      stood.  Expecting network numbers to fit in no more than 32 bits is
1137      naive.
1138
1139 BSD                             March 13, 1997                             BSD
1140     </screen>
1141   </sect1>
1142
1143   <sect1 id="net-common-tcpip-manpages-getprotoent">
1144     <title>getprotoent</title>
1145     <screen>
1146 GETPROTOENT(3)           BSD Library Functions Manual           GETPROTOENT(3)
1147
1148 NAME
1149      getprotoent, getprotobynumber, getprotobyname, setprotoent, endprotoent -
1150      get protocol entry
1151
1152 SYNOPSIS
1153      #include &lt;netdb.h>
1154
1155      struct protoent *
1156      getprotoent(void);
1157
1158      struct protoent *
1159      getprotobyname(char *name);
1160
1161      struct protoent *
1162      getprotobynumber(int proto);
1163
1164      void
1165      setprotoent(int stayopen);
1166
1167      void
1168      endprotoent(void);
1169
1170 DESCRIPTION
1171      The getprotoent(), getprotobyname(), and getprotobynumber() functions
1172      each return a pointer to an object with the following structure contain-
1173      ing the broken-out fields of a line in the network protocol database,
1174      /etc/protocols.
1175
1176
1177            struct  protoent {
1178                    char    *p_name;        /* official name of protocol */
1179                    char    **p_aliases;    /* alias list */
1180                    int     p_proto;        /* protocol number */
1181            };
1182
1183      The members of this structure are:
1184
1185      p_name     The official name of the protocol.
1186
1187      p_aliases  A zero-terminated list of alternate names for the protocol.
1188
1189      p_proto    The protocol number.
1190
1191      The getprotoent() function reads the next line of the file, opening the
1192      file if necessary.
1193
1194      The setprotoent() function opens and rewinds the file.  If the stayopen
1195      flag is non-zero, the net database will not be closed after each call to
1196      getprotobyname() or getprotobynumber().
1197
1198      The endprotoent() function closes the file.
1199
1200      The getprotobyname() and getprotobynumber() functions sequentially search
1201      from the beginning of the file until a matching protocol name or protocol
1202      number is found, or until EOF is encountered.
1203
1204 RETURN VALUES
1205      Null pointer (0) returned on EOF or error.
1206
1207 FILES
1208      /etc/protocols
1209
1210 SEE ALSO
1211      protocols(5)
1212
1213 HISTORY
1214      The getprotoent(), getprotobynumber(), getprotobyname(), setprotoent(),
1215      and endprotoent() functions appeared in 4.2BSD.
1216
1217 BUGS
1218      These functions use a static data space; if the data is needed for future
1219      use, it should be copied before any subsequent calls overwrite it.  Only
1220      the Internet protocols are currently understood.
1221
1222 BSD                              June 4, 1993                              BSD
1223     </screen>
1224   </sect1>
1225
1226   <sect1 id="net-common-tcpip-manpages-getrrsetbyname">
1227     <title>getrrsetbyname</title>
1228     <screen>
1229 GETRRSETBYNAME(3)        BSD Library Functions Manual        GETRRSETBYNAME(3)
1230
1231 NAME
1232      getrrsetbyname - retrieve DNS records
1233
1234 SYNOPSIS
1235      #include &lt;netdb.h>
1236
1237      int
1238      getrrsetbyname(const char *hostname, unsigned int rdclass,
1239              unsigned int rdtype, unsigned int flags, struct rrsetinfo **res);
1240
1241      int
1242      freerrset(struct rrsetinfo **rrset);
1243
1244 DESCRIPTION
1245      getrrsetbyname() gets a set of resource records associated with a
1246      hostname, class and type.  hostname is a pointer a to null-terminated
1247      string.  The flags field is currently unused and must be zero.
1248
1249      After a successful call to getrrsetbyname(), *res is a pointer to an
1250      rrsetinfo structure, containing a list of one or more rdatainfo struc-
1251      tures containing resource records and potentially another list of
1252      rdatainfo structures containing SIG resource records associated with
1253      those records.  The members rri_rdclass and rri_rdtype are copied from
1254      the parameters.  rri_ttl and rri_name are properties of the obtained
1255      rrset.  The resource records contained in rri_rdatas and rri_sigs are in
1256      uncompressed DNS wire format.  Properties of the rdataset are represented
1257      in the rri_flags bitfield. If the RRSET_VALIDATED bit is set, the data
1258      has been DNSSEC validated and the signatures verified.
1259
1260      The following structures are used:
1261
1262      struct  rdatainfo {
1263              unsigned int            rdi_length;     /* length of data */
1264              unsigned char           *rdi_data;      /* record data */
1265      };
1266
1267      struct  rrsetinfo {
1268              unsigned int            rri_flags;      /* RRSET_VALIDATED ... */
1269              unsigned int            rri_rdclass;    /* class number */
1270              unsigned int            rri_rdtype;     /* RR type number */
1271              unsigned int            rri_ttl;        /* time to live */
1272              unsigned int            rri_nrdatas;    /* size of rdatas array */
1273              unsigned int            rri_nsigs;      /* size of sigs array */
1274              char                    *rri_name;      /* canonical name */
1275              struct rdatainfo        *rri_rdatas;    /* individual records */
1276              struct rdatainfo        *rri_sigs;      /* individual signatures */
1277      };
1278
1279      All of the information returned by getrrsetbyname() is dynamically allo-
1280      cated: the rrsetinfo and rdatainfo structures, and the canonical host
1281      name strings pointed to by the rrsetinfostructure. Memory allocated for
1282      the dynamically allocated structures created by a successful call to
1283      getrrsetbyname() is released by freerrset().  rrset is a pointer to a
1284      struct rrset created by a call to getrrsetbyname().
1285
1286      If the EDNS0 option is activated in resolv.conf(3), getrrsetbyname() will
1287      request DNSSEC authentication using the EDNS0 DNSSEC OK (DO) bit.
1288
1289 RETURN VALUES
1290      getrrsetbyname() returns zero on success, and one of the following error
1291      codes if an error occurred:
1292
1293      ERRSET_NONAME    the name does not exist
1294      ERRSET_NODATA    the name exists, but does not have data of the desired
1295                       type
1296      ERRSET_NOMEMORY  memory could not be allocated
1297      ERRSET_INVAL     a parameter is invalid
1298      ERRSET_FAIL      other failure
1299
1300 SEE ALSO
1301      resolver(3), resolv.conf(5), named(8)
1302
1303 AUTHORS
1304      Jakob Schlyter &lt;jakob@openbsd.org>
1305
1306 HISTORY
1307      getrrsetbyname() first appeared in OpenBSD 3.0.  The API first appeared
1308      in ISC BIND version 9.
1309
1310 BUGS
1311      The data in *rdi_data should be returned in uncompressed wire format.
1312      Currently, the data is in compressed format and the caller can't uncom-
1313      press since it doesn't have the full message.
1314
1315 CAVEATS
1316      The RRSET_VALIDATED flag in rri_flags is set if the AD (autenticated
1317      data) bit in the DNS answer is set. This flag should not be trusted
1318      unless the transport between the nameserver and the resolver is secure
1319      (e.g. IPsec, trusted network, loopback communication).
1320
1321 BSD                              Oct 18, 2000                              BSD
1322     </screen>
1323   </sect1>
1324
1325   <sect1 id="net-common-tcpip-manpages-getservent">
1326     <title>getservent</title>
1327     <screen>
1328 GETSERVENT(3)            BSD Library Functions Manual            GETSERVENT(3)
1329
1330 NAME
1331      getservent, getservbyport, getservbyname, setservent, endservent - get
1332      service entry
1333
1334 SYNOPSIS
1335      #include &lt;netdb.h>
1336
1337      struct servent *
1338      getservent(void);
1339
1340      struct servent *
1341      getservbyname(char *name, char *proto);
1342
1343      struct servent *
1344      getservbyport(int port, char *proto);
1345
1346      void
1347      setservent(int stayopen);
1348
1349      void
1350      endservent(void);
1351
1352 DESCRIPTION
1353      The getservent(), getservbyname(), and getservbyport() functions each
1354      return a pointer to an object with the following structure containing the
1355      broken-out fields of a line in the network services database,
1356      /etc/services.
1357
1358            struct  servent {
1359                    char    *s_name;        /* official name of service */
1360                    char    **s_aliases;    /* alias list */
1361                    int     s_port;         /* port service resides at */
1362                    char    *s_proto;       /* protocol to use */
1363            };
1364
1365      The members of this structure are:
1366
1367      s_name     The official name of the service.
1368
1369      s_aliases  A zero-terminated list of alternate names for the service.
1370
1371      s_port     The port number at which the service resides.  Port numbers
1372                 are returned in network byte order.
1373
1374      s_proto    The name of the protocol to use when contacting the service.
1375
1376      The getservent() function reads the next line of the file, opening the
1377      file if necessary.
1378
1379      The setservent() function opens and rewinds the file.  If the stayopen
1380      flag is non-zero, the net database will not be closed after each call to
1381      getservbyname() or getservbyport().
1382
1383      The endservent() function closes the file.
1384
1385      The getservbyname() and getservbyport() functions sequentially search
1386      from the beginning of the file until a matching protocol name or port
1387      number (specified in network byte order) is found, or until EOF is
1388      encountered.  If a protocol name is also supplied (non-null), searches
1389      must also match the protocol.
1390
1391 FILES
1392      /etc/services
1393
1394 DIAGNOSTICS
1395      Null pointer (0) returned on EOF or error.
1396
1397 SEE ALSO
1398      getprotoent(3), services(5)
1399
1400 HISTORY
1401      The getservent(), getservbyport(), getservbyname(), setservent(), and
1402      endservent() functions appeared in 4.2BSD.
1403
1404 BUGS
1405      These functions use static data storage; if the data is needed for future
1406      use, it should be copied before any subsequent calls overwrite it.
1407      Expecting port numbers to fit in a 32-bit quantity is probably naive.
1408
1409 BSD                            January 12, 1994                            BSD
1410     </screen>
1411   </sect1>
1412
1413   <sect1 id="net-common-tcpip-manpages-if-nametoindex">
1414     <title>if_nametoindex</title>
1415     <screen>
1416 IF_NAMETOINDEX(3)        BSD Library Functions Manual        IF_NAMETOINDEX(3)
1417
1418 NAME
1419      if_nametoindex, if_indextoname, if_nameindex, if_freenameindex - convert
1420      interface index to name, and vice versa
1421
1422 SYNOPSIS
1423      #include &lt;net/if.h>
1424
1425      unsigned int
1426      if_nametoindex(const char *ifname);
1427
1428      char *
1429      if_indextoname(unsigned int ifindex, char *ifname);
1430
1431      struct if_nameindex *
1432      if_nameindex(void);
1433
1434      void
1435      if_freenameindex(struct if_nameindex *ptr);
1436
1437 DESCRIPTION
1438      These functions map interface indexes to interface names (such as
1439      ``lo0''), and vice versa.
1440
1441      The if_nametoindex() function converts an interface name specified by the
1442      ifname argument to an interface index (positive integer value).  If the
1443      specified interface does not exist, 0 will be returned.
1444
1445      if_indextoname() converts an interface index specified by the ifindex
1446      argument to an interface name.  The ifname argument must point to a
1447      buffer of at least IF_NAMESIZE bytes into which the interface name corre-
1448      sponding to the specified index is returned.  (IF_NAMESIZE is also
1449      defined in &lt;net/if.h> and its value includes a terminating null byte at
1450      the end of the interface name.)  This pointer is also the return value of
1451      the function.  If there is no interface corresponding to the specified
1452      index, NULL is returned.
1453
1454      if_nameindex() returns an array of if_nameindex structures.
1455      if_nametoindex is also defined in &lt;net/if.h>, and is as follows:
1456
1457      struct if_nameindex {
1458          unsigned int   if_index;  /* 1, 2, ... */
1459          char          *if_name;   /* null terminated name: "le0", ... */
1460      };
1461
1462      The end of the array of structures is indicated by a structure with an
1463      if_index of 0 and an if_name of NULL.  The function returns a null
1464      pointer on error.  The memory used for this array of structures along
1465      with the interface names pointed to by the if_name members is obtained
1466      dynamically.  This memory is freed by the if_freenameindex() function.
1467
1468      if_freenameindex() takes a pointer that was returned by if_nameindex() as
1469      argument (ptr), and it reclaims the region allocated.
1470
1471 DIAGNOSTICS
1472      if_nametoindex() returns 0 on error, positive integer on success.
1473      if_indextoname() and if_nameindex() return NULL on errors.
1474
1475 SEE ALSO
1476      R. Gilligan, S.  Thomson, J. Bound, and W. Stevens, ``Basic Socket Inter-
1477      face Extensions for IPv6,'' RFC2553, March 1999.
1478
1479 STANDARDS
1480      These functions are defined in ``Basic Socket Interface Extensions for
1481      IPv6'' (RFC2533).
1482
1483 BSD                              May 21, 1998                              BSD
1484     </screen>
1485   </sect1>
1486
1487   <sect1 id="net-common-tcpip-manpages-inet">
1488     <title>inet</title>
1489     <screen>
1490 INET(3)                  BSD Library Functions Manual                  INET(3)
1491
1492 NAME
1493      inet_addr, inet_aton, inet_lnaof, inet_makeaddr, inet_netof,
1494      inet_network, inet_ntoa, inet_ntop, inet_pton - Internet address manipu-
1495      lation routines
1496
1497 SYNOPSIS
1498      #include &lt;sys/socket.h>
1499      #include &lt;netinet/in.h>
1500      #include &lt;arpa/inet.h>
1501
1502      in_addr_t
1503      inet_addr(const char *cp);
1504
1505      int
1506      inet_aton(const char *cp, struct in_addr *addr);
1507
1508      in_addr_t
1509      inet_lnaof(struct in_addr in);
1510
1511      struct in_addr
1512      inet_makeaddr(unsigned long net, unsigned long lna);
1513
1514      in_addr_t
1515      inet_netof(struct in_addr in);
1516
1517      in_addr_t
1518      inet_network(const char *cp);
1519
1520      char *
1521      inet_ntoa(struct in_addr in);
1522
1523      const char *
1524      inet_ntop(int af, const void *src, char *dst, size_t size);
1525
1526      int
1527      inet_pton(int af, const char *src, void *dst);
1528
1529 DESCRIPTION
1530      The routines inet_aton(), inet_addr() and inet_network() interpret char-
1531      acter strings representing numbers expressed in the Internet standard '.'
1532      notation.  The inet_pton() function converts a presentation format
1533      address (that is, printable form as held in a character string) to net-
1534      work format (usually a struct in_addr or some other internal binary rep-
1535      resentation, in network byte order).  It returns 1 if the address was
1536      valid for the specified address family, or 0 if the address wasn't
1537      parseable in the specified address family, or -1 if some system error
1538      occurred (in which case errno will have been set).  This function is
1539      presently valid for AF_INET and AF_INET6.  The inet_aton() routine inter-
1540      prets the specified character string as an Internet address, placing the
1541      address into the structure provided.  It returns 1 if the string was suc-
1542      cessfully interpreted, or 0 if the string was invalid.  The inet_addr()
1543      and inet_network() functions return numbers suitable for use as Internet
1544      addresses and Internet network numbers, respectively.
1545
1546      The function inet_ntop() converts an address from network format (usually
1547      a struct in_addr or some other binary form, in network byte order) to
1548      presentation format (suitable for external display purposes).  It returns
1549      NULL if a system error occurs (in which case, errno will have been set),
1550      or it returns a pointer to the destination string.  The routine
1551      inet_ntoa() takes an Internet address and returns an ASCII string repre-
1552      senting the address in '.' notation.  The routine inet_makeaddr() takes
1553      an Internet network number and a local network address and constructs an
1554      Internet address from it.  The routines inet_netof() and inet_lnaof()
1555      break apart Internet host addresses, returning the network number and
1556      local network address part, respectively.
1557
1558      All Internet addresses are returned in network order (bytes ordered from
1559      left to right).  All network numbers and local address parts are returned
1560      as machine format integer values.
1561
1562 INTERNET ADDRESSES (IP VERSION 4)
1563      Values specified using the '.' notation take one of the following forms:
1564
1565            a.b.c.d
1566            a.b.c
1567            a.b
1568            a
1569
1570      When four parts are specified, each is interpreted as a byte of data and
1571      assigned, from left to right, to the four bytes of an Internet address.
1572      Note that when an Internet address is viewed as a 32-bit integer quantity
1573      on a system that uses little-endian byte order (such as the Intel 386,
1574      486 and Pentium processors) the bytes referred to above appear as
1575      ``d.c.b.a''.  That is, little-endian bytes are ordered from right to
1576      left.
1577
1578      When a three part address is specified, the last part is interpreted as a
1579      16-bit quantity and placed in the rightmost two bytes of the network
1580      address.  This makes the three part address format convenient for speci-
1581      fying Class B network addresses as ``128.net.host''.
1582
1583      When a two part address is supplied, the last part is interpreted as a
1584      24-bit quantity and placed in the rightmost three bytes of the network
1585      address.  This makes the two part address format convenient for specify-
1586      ing Class A network addresses as ``net.host''.
1587
1588      When only one part is given, the value is stored directly in the network
1589      address without any byte rearrangement.
1590
1591      All numbers supplied as ``parts'' in a '.' notation may be decimal,
1592      octal, or hexadecimal, as specified in the C language (i.e., a leading 0x
1593      or 0X implies hexadecimal; otherwise, a leading 0 implies octal; other-
1594      wise, the number is interpreted as decimal).
1595
1596 INTERNET ADDRESSES (IP VERSION 6)
1597      In order to support scoped IPv6 addresses, getaddrinfo(3) and
1598      getnameinfo(3) are recommended rather than the functions presented here.
1599
1600      The presentation format of an IPv6 address is given in [RFC1884 2.2]:
1601
1602      There are three conventional forms for representing IPv6 addresses as
1603      text strings:
1604
1605      1.   The preferred form is x:x:x:x:x:x:x:x, where the 'x's are the hex-
1606           adecimal values of the eight 16-bit pieces of the address.  Exam-
1607           ples:
1608
1609                 FEDC:BA98:7654:3210:FEDC:BA98:7654:3210
1610                 1080:0:0:0:8:800:200C:417A
1611
1612           Note that it is not necessary to write the leading zeros in an indi-
1613           vidual field, but there must be at least one numeral in every field
1614           (except for the case described in 2.).
1615
1616      2.   Due to the method of allocating certain styles of IPv6 addresses, it
1617           will be common for addresses to contain long strings of zero bits.
1618           In order to make writing addresses
1619
1620           containing zero bits easier a special syntax is available to com-
1621           press the zeros.  The use of ``::'' indicates multiple groups of 16
1622           bits of zeros.  The ``::'' can only appear once in an address.  The
1623           ``::'' can also be used to compress the leading and/or trailing
1624           zeros in an address.
1625
1626           For example the following addresses:
1627
1628                 1080:0:0:0:8:800:200C:417A  a unicast address
1629                 FF01:0:0:0:0:0:0:43         a multicast address
1630                 0:0:0:0:0:0:0:1             the loopback address
1631                 0:0:0:0:0:0:0:0             the unspecified addresses
1632
1633           may be represented as:
1634
1635                 1080::8:800:200C:417A       a unicast address
1636                 FF01::43                    a multicast address
1637                 ::1                         the loopback address
1638                 ::                          the unspecified addresses
1639
1640      3.   An alternative form that is sometimes more convenient when dealing
1641           with a mixed environment of IPv4 and IPv6 nodes is
1642           x:x:x:x:x:x:d.d.d.d, where the 'x's are the hexadecimal values of
1643           the six high-order 16-bit pieces of the address, and the 'd's are
1644           the decimal values of the four low-order 8-bit pieces of the address
1645           (standard IPv4 representation).  Examples:
1646
1647                 0:0:0:0:0:0:13.1.68.3
1648                 0:0:0:0:0:FFFF:129.144.52.38
1649
1650           or in compressed form:
1651
1652                 ::13.1.68.3
1653                 ::FFFF:129.144.52.38
1654
1655 DIAGNOSTICS
1656      The constant INADDR_NONE is returned by inet_addr() and inet_network()
1657      for malformed requests.
1658
1659 SEE ALSO
1660      byteorder(3), gethostbyname(3), getnetent(3), inet_net(3), hosts(5),
1661      networks(5)
1662
1663 STANDARDS
1664      The inet_ntop and inet_pton functions conforms to the IETF IPv6 BSD API
1665      and address formatting specifications.  Note that inet_pton does not
1666      accept 1-, 2-, or 3-part dotted addresses; all four parts must be speci-
1667      fied.  This is a narrower input set than that accepted by inet_aton.
1668
1669 HISTORY
1670      The inet_addr, inet_network, inet_makeaddr, inet_lnaof and inet_netof
1671      functions appeared in 4.2BSD.  The inet_aton and inet_ntoa functions
1672      appeared in 4.3BSD.  The inet_pton and inet_ntop functions appeared in
1673      BIND 4.9.4.
1674
1675 BUGS
1676      The value INADDR_NONE (0xffffffff) is a valid broadcast address, but
1677      inet_addr() cannot return that value without indicating failure.  Also,
1678      inet_addr() should have been designed to return a struct in_addr.  The
1679      newer inet_aton() function does not share these problems, and almost all
1680      existing code should be modified to use inet_aton() instead.
1681
1682      The problem of host byte ordering versus network byte ordering is confus-
1683      ing.
1684
1685      The string returned by inet_ntoa() resides in a static memory area.
1686
1687 BSD                              June 18, 1997                             BSD
1688     </screen>
1689   </sect1>
1690
1691   <sect1 id="net-common-tcpip-manpages-inet6-option-space">
1692     <title>inet6_option_space</title>
1693     <screen>
1694 INET6_OPTION_SPACE(3)    BSD Library Functions Manual    INET6_OPTION_SPACE(3)
1695
1696 NAME
1697      inet6_option_space, inet6_option_init, inet6_option_append,
1698      inet6_option_alloc, inet6_option_next, inet6_option_find - IPv6 Hop-by-
1699      Hop and Destination Options manipulation
1700
1701 SYNOPSIS
1702      #include &lt;netinet/in.h>
1703
1704      int
1705      inet6_option_space(int nbytes);
1706
1707      int
1708      inet6_option_init(void *bp, struct cmsghdr **cmsgp, int type);
1709
1710      int
1711      inet6_option_append(struct cmsghdr *cmsg, const u_int8_t *typep,
1712              int multx, int plusy);
1713
1714      u_int8_t *
1715      inet6_option_alloc(struct cmsghdr *cmsg, int datalen, int multx,
1716              int plusy);;
1717
1718      int
1719      inet6_option_next(const struct cmsghdr *cmsg, u_int8_t **tptrp);
1720
1721      int
1722      inet6_option_find(const struct cmsghdr *cmsg, u_int8_t **tptrp,
1723              int type);
1724
1725 DESCRIPTION
1726      Building and parsing the Hop-by-Hop and Destination options is compli-
1727      cated due to alignment constranints, padding and ancillary data manipula-
1728      tion.  RFC2292 defines a set of functions to help the application.  The
1729      function prototypes for these functions are all in the &lt;netinet/in.h>
1730      header.
1731
1732    inet6_option_space
1733      inet6_option_space() returns the number of bytes required to hold an
1734      option when it is stored as ancillary data, including the cmsghdr struc-
1735      ture at the beginning, and any padding at the end (to make its size a
1736      multiple of 8 bytes).  The argument is the size of the structure defining
1737      the option, which must include any pad bytes at the beginning (the value
1738      y in the alignment term ``xn + y''), the type byte, the length byte, and
1739      the option data.
1740
1741      Note: If multiple options are stored in a single ancillary data object,
1742      which is the recommended technique, this function overestimates the
1743      amount of space required by the size of N-1 cmsghdr structures, where N
1744      is the number of options to be stored in the object.  This is of little
1745      consequence, since it is assumed that most Hop-by-Hop option headers and
1746      Destination option headers carry only one option (appendix B of
1747      [RFC-2460]).
1748
1749    inet6_option_init
1750      inet6_option_init() is called once per ancillary data object that will
1751      contain either Hop-by-Hop or Destination options.  It returns 0 on suc-
1752      cess or -1 on an error.
1753
1754      bp is a pointer to previously allocated space that will contain the
1755      ancillary data object.  It must be large enough to contain all the indi-
1756      vidual options to be added by later calls to inet6_option_append() and
1757      inet6_option_alloc().
1758
1759      cmsgp is a pointer to a pointer to a cmsghdr structure.  *cmsgp is ini-
1760      tialized by this function to point to the cmsghdr structure constructed
1761      by this function in the buffer pointed to by bp.
1762
1763      type is either IPV6_HOPOPTS or IPV6_DSTOPTS.  This type is stored in the
1764      cmsg_type member of the cmsghdr structure pointed to by *cmsgp.
1765
1766    inet6_option_append
1767      This function appends a Hop-by-Hop option or a Destination option into an
1768      ancillary data object that has been initialized by inet6_option_init().
1769      This function returns 0 if it succeeds or -1 on an error.
1770
1771      cmsg is a pointer to the cmsghdr structure that must have been initial-
1772      ized by inet6_option_init().
1773
1774      typep is a pointer to the 8-bit option type.  It is assumed that this
1775      field is immediately followed by the 8-bit option data length field,
1776      which is then followed immediately by the option data.  The caller ini-
1777      tializes these three fields (the type-length-value, or TLV) before call-
1778      ing this function.
1779
1780      The option type must have a value from 2 to 255, inclusive.  (0 and 1 are
1781      reserved for the Pad1 and PadN options, respectively.)
1782
1783      The option data length must have a value between 0 and 255, inclusive,
1784      and is the length of the option data that follows.
1785
1786      multx is the value x in the alignment term ``xn + y''.  It must have a
1787      value of 1, 2, 4, or 8.
1788
1789      plusy is the value y in the alignment term ``xn + y''.  It must have a
1790      value between 0 and 7, inclusive.
1791
1792    inet6_option_alloc
1793      This function appends a Hop-by-Hop option or a Destination option into an
1794      ancillary data object that has been initialized by inet6_option_init().
1795      This function returns a pointer to the 8-bit option type field that
1796      starts the option on success, or NULL on an error.
1797
1798      The difference between this function and inet6_option_append() is that
1799      the latter copies the contents of a previously built option into the
1800      ancillary data object while the current function returns a pointer to the
1801      space in the data object where the option's TLV must then be built by the
1802      caller.
1803
1804      cmsg is a pointer to the cmsghdr structure that must have been initial-
1805      ized by inet6_option_init().
1806
1807      datalen is the value of the option data length byte for this option.
1808      This value is required as an argument to allow the function to determine
1809      if padding must be appended at the end of the option.  (The
1810      inet6_option_append() function does not need a data length argument since
1811      the option data length must already be stored by the caller.)
1812
1813      multx is the value x in the alignment term ``xn + y''.  It must have a
1814      value of 1, 2, 4, or 8.
1815
1816      plusy is the value y in the alignment term ``xn + y''.  It must have a
1817      value between 0 and 7, inclusive.
1818
1819    inet6_option_next
1820      This function processes the next Hop-by-Hop option or Destination option
1821      in an ancillary data object.  If another option remains to be processed,
1822      the return value of the function is 0 and *tptrp points to the 8-bit
1823      option type field (which is followed by the 8-bit option data length,
1824      followed by the option data).  If no more options remain to be processed,
1825      the return value is -1 and *tptrp is NULL.  If an error occurs, the
1826      return value is -1 and *tptrp is not NULL.
1827
1828      cmsg is a pointer to cmsghdr structure of which cmsg_level equals
1829      IPPROTO_IPV6 and cmsg_type equals either IPV6_HOPOPTS or IPV6_DSTOPTS.
1830
1831      tptrp is a pointer to a pointer to an 8-bit byte and *tptrp is used by
1832      the function to remember its place in the ancillary data object each time
1833      the function is called.  The first time this function is called for a
1834      given ancillary data object, *tptrp must be set to NULL.
1835
1836      Each time this function returns success, *tptrp points to the 8-bit
1837      option type field for the next option to be processed.
1838
1839    inet6_option_find
1840      This function is similar to the previously described inet6_option_next()
1841      function, except this function lets the caller specify the option type to
1842      be searched for, instead of always returning the next option in the
1843      ancillary data object.  cmsg is a pointer to cmsghdr structure of which
1844      cmsg_level equals IPPROTO_IPV6 and cmsg_type equals either IPV6_HOPOPTS
1845      or IPV6_DSTOPTS.
1846
1847      tptrp is a pointer to a pointer to an 8-bit byte and *tptrp is used by
1848      the function to remember its place in the ancillary data object each time
1849      the function is called.  The first time this function is called for a
1850      given ancillary data object, *tptrp must be set to NULL.  ~ This function
1851      starts searching for an option of the specified type beginning after the
1852      value of *tptrp.  If an option of the specified type is located, this
1853      function returns 0 and *tptrp points to the 8- bit option type field for
1854      the option of the specified type.  If an option of the specified type is
1855      not located, the return value is -1 and *tptrp is NULL.  If an error
1856      occurs, the return value is -1 and *tptrp is not NULL.
1857
1858 DIAGNOSTICS
1859      inet6_option_init() and inet6_option_append() return 0 on success or -1
1860      on an error.
1861
1862      inet6_option_alloc() returns NULL on an error.
1863
1864      On errors, inet6_option_next() and inet6_option_find() return -1 setting
1865      *tptrp to non NULL value.
1866
1867 EXAMPLES
1868      RFC2292 gives comprehensive examples in chapter 6.
1869
1870 SEE ALSO
1871      W. Stevens and M. Thomas, Advanced Sockets API for IPv6, RFC2292,
1872      February 1998.
1873
1874      S. Deering and R. Hinden, Internet Protocol, Version 6 (IPv6)
1875      Specification, RFC2460, December 1998.
1876
1877 HISTORY
1878      The implementation first appeared in KAME advanced networking kit.
1879
1880 STANDARDS
1881      The functions are documented in ``Advanced Sockets API for IPv6''
1882      (RFC2292).
1883
1884 BUGS
1885      The text was shamelessly copied from RFC2292.
1886
1887 BSD                            December 10, 1999                           BSD
1888     </screen>
1889   </sect1>
1890
1891   <sect1 id="net-common-tcpip-manpages-inet6-rthdr-space">
1892     <title>inet6_rthdr_space</title>
1893     <screen>
1894 INET6_RTHDR_SPACE(3)     BSD Library Functions Manual     INET6_RTHDR_SPACE(3)
1895
1896 NAME
1897      inet6_rthdr_space, inet6_rthdr_init, inet6_rthdr_add,
1898      inet6_rthdr_lasthop, inet6_rthdr_reverse, inet6_rthdr_segments,
1899      inet6_rthdr_getaddr, inet6_rthdr_getflags - IPv6 Routing Header Options
1900      manipulation
1901
1902 SYNOPSIS
1903      #include &lt;netinet/in.h>
1904
1905      size_t
1906      inet6_rthdr_space(int type, int segments);
1907
1908      struct cmsghdr *
1909      inet6_rthdr_init(void *bp, int type);
1910
1911      int
1912      inet6_rthdr_add(struct cmsghdr *cmsg, const struct in6_addr *addr,
1913              unsigned int flags);
1914
1915      int
1916      inet6_rthdr_lasthop(struct cmsghdr *cmsg, unsigned int flags);
1917
1918      int
1919      inet6_rthdr_reverse(const struct cmsghdr *in, struct cmsghdr *out);
1920
1921      int
1922      inet6_rthdr_segments(const struct cmsghdr *cmsg);
1923
1924      struct in6_addr *
1925      inet6_rthdr_getaddr(struct cmsghdr *cmsg, int index);
1926
1927      int
1928      inet6_rthdr_getflags(const struct cmsghdr *cmsg, int index);
1929
1930 DESCRIPTION
1931      RFC2292 IPv6 advanced API defines eight functions that the application
1932      calls to build and examine a Routing header.  Four functions build a
1933      Routing header:
1934
1935      inet6_rthdr_space() return #bytes required for ancillary data
1936
1937      inet6_rthdr_init() initialize ancillary data for Routing header
1938
1939      inet6_rthdr_add() add IPv6 address &amp; flags to Routing header
1940
1941      inet6_rthdr_lasthop() specify the flags for the final hop
1942
1943      Four functions deal with a returned Routing header:
1944
1945      inet6_rthdr_reverse() reverse a Routing header
1946
1947      inet6_rthdr_segments() return #segments in a Routing header
1948
1949      inet6_rthdr_getaddr() fetch one address from a Routing header
1950
1951      inet6_rthdr_getflags() fetch one flag from a Routing header
1952
1953      The function prototypes for these functions are all in the &lt;netinet/in.h>
1954      header.
1955
1956    inet6_rthdr_space
1957      This function returns the number of bytes required to hold a Routing
1958      header of the specified type containing the specified number of segments
1959      (addresses).  For an IPv6 Type 0 Routing header, the number of segments
1960      must be between 1 and 23, inclusive.  The return value includes the size
1961      of the cmsghdr structure that precedes the Routing header, and any
1962      required padding.
1963
1964      If the return value is 0, then either the type of the Routing header is
1965      not supported by this implementation or the number of segments is invalid
1966      for this type of Routing header.
1967
1968      Note: This function returns the size but does not allocate the space
1969      required for the ancillary data.  This allows an application to allocate
1970      a larger buffer, if other ancillary data objects are desired, since all
1971      the ancillary data objects must be specified to sendmsg(2) as a single
1972      msg_control buffer.
1973
1974    inet6_rthdr_init
1975      This function initializes the buffer pointed to by bp to contain a
1976      cmsghdr structure followed by a Routing header of the specified type.
1977      The cmsg_len member of the cmsghdr structure is initialized to the size
1978      of the structure plus the amount of space required by the Routing header.
1979      The cmsg_level and cmsg_type members are also initialized as required.
1980
1981      The caller must allocate the buffer and its size can be determined by
1982      calling inet6_rthdr_space().
1983
1984      Upon success the return value is the pointer to the cmsghdr structure,
1985      and this is then used as the first argument to the next two functions.
1986      Upon an error the return value is NULL.
1987
1988    inet6_rthdr_add
1989      This function adds the address pointed to by addr to the end of the Rout-
1990      ing header being constructed and sets the type of this hop to the value
1991      of flags.  For an IPv6 Type 0 Routing header, flags must be either
1992      IPV6_RTHDR_LOOSE or IPV6_RTHDR_STRICT.
1993
1994      If successful, the cmsg_len member of the cmsghdr structure is updated to
1995      account for the new address in the Routing header and the return value of
1996      the function is 0.  Upon an error the return value of the function is -1.
1997
1998    inet6_rthdr_lasthop
1999      This function specifies the Strict/Loose flag for the final hop of a
2000      Routing header.  For an IPv6 Type 0 Routing header, flags must be either
2001      IPV6_RTHDR_LOOSE or IPV6_RTHDR_STRICT.
2002
2003      The return value of the function is 0 upon success, or -1 upon an error.
2004
2005      Notice that a Routing header specifying N intermediate nodes requires N+1
2006      Strict/Loose flags.  This requires N calls to inet6_rthdr_add() followed
2007      by one call to inet6_rthdr_lasthop().
2008
2009    inet6_rthdr_reverse
2010      This function takes a Routing header that was received as ancillary data
2011      (pointed to by the first argument, in) and writes a new Routing header
2012      that sends datagrams along the reverse of that route.  Both arguments are
2013      allowed to point to the same buffer (that is, the reversal can occur in
2014      place).
2015
2016      The return value of the function is 0 on success, or -1 upon an error.
2017
2018    inet6_rthdr_segments
2019      This function returns the number of segments (addresses) contained in the
2020      Routing header described by cmsg.  On success the return value is between
2021      1 and 23, inclusive.  The return value of the function is -1 upon an
2022      error.
2023
2024    inet6_rthdr_getaddr
2025      This function returns a pointer to the IPv6 address specified by index
2026      (which must have a value between 1 and the value returned by
2027      inet6_rthdr_segments()) in the Routing header described by cmsg.  An
2028      application should first call inet6_rthdr_segments() to obtain the number
2029      of segments in the Routing header.
2030
2031      Upon an error the return value of the function is NULL.
2032
2033    inet6_rthdr_getflags
2034      This function returns the flags value specified by index (which must have
2035      a value between 0 and the value returned by inet6_rthdr_segments()) in
2036      the Routing header described by cmsg.  For an IPv6 Type 0 Routing header
2037      the return value will be either IPV6_RTHDR_LOOSE or IPV6_RTHDR_STRICT.
2038
2039      Upon an error the return value of the function is -1.
2040
2041      Note: Addresses are indexed starting at 1, and flags starting at 0, to
2042      maintain consistency with the terminology and figures in RFC2460.
2043
2044 DIAGNOSTICS
2045      inet6_rthdr_space() returns 0 on errors.
2046
2047      inet6_rthdr_add(), inet6_rthdr_lasthop() and inet6_rthdr_reverse() return
2048      0 on success, and returns -1 on error.
2049
2050      inet6_rthdr_init() and inet6_rthdr_getaddr() return NULL on error.
2051
2052      inet6_rthdr_segments() and inet6_rthdr_getflags() return -1 on error.
2053
2054 EXAMPLES
2055      RFC2292 gives comprehensive examples in chapter 8.
2056
2057 SEE ALSO
2058      W. Stevens and M. Thomas, Advanced Sockets API for IPv6, RFC2292,
2059      February 1998.
2060
2061      S. Deering and R. Hinden, Internet Protocol, Version 6 (IPv6)
2062      Specification, RFC2460, December 1998.
2063
2064 HISTORY
2065      The implementation first appeared in KAME advanced networking kit.
2066
2067 STANDARDS
2068      The functions are documented in ``Advanced Sockets API for IPv6''
2069      (RFC2292).
2070
2071 BUGS
2072      The text was shamelessly copied from RFC2292.
2073
2074      inet6_rthdr_reverse() is not implemented yet.
2075
2076 BSD                            December 10, 1999                           BSD
2077     </screen>
2078   </sect1>
2079
2080   <sect1 id="net-common-tcpip-manpages-inet-net">
2081     <title>inet_net</title>
2082     <screen>
2083 INET_NET(3)              BSD Library Functions Manual              INET_NET(3)
2084
2085 NAME
2086      inet_net_ntop, inet_net_pton - Internet network number manipulation rou-
2087      tines
2088
2089 SYNOPSIS
2090      #include &lt;sys/socket.h>
2091      #include &lt;netinet/in.h>
2092      #include &lt;arpa/inet.h>
2093
2094      char *
2095      inet_net_ntop(int af, const void *src, int bits, char *dst, size_t size);
2096
2097      int
2098      inet_net_pton(int af, const char *src, void *dst, size_t size);
2099
2100 DESCRIPTION
2101      The inet_net_ntop() function converts an Internet network number from
2102      network format (usually a struct in_addr or some other binary form, in
2103      network byte order) to CIDR presentation format (suitable for external
2104      display purposes).  bits is the number of bits in src that are the net-
2105      work number.  It returns NULL if a system error occurs (in which case,
2106      errno will have been set), or it returns a pointer to the destination
2107      string.
2108
2109      The inet_net_pton() function converts a presentation format Internet net-
2110      work number (that is, printable form as held in a character string) to
2111      network format (usually a struct in_addr or some other internal binary
2112      representation, in network byte order).  It returns the number of bits
2113      (either computed based on the class, or specified with /CIDR), or -1 if a
2114      failure occurred (in which case errno will have been set.  It will be set
2115      to ENOENT if the Internet network number was not valid).
2116
2117      The only value for af currently supported is AF_INET.  size is the size
2118      of the result buffer dst.
2119
2120 NETWORK NUMBERS (IP VERSION 4)
2121      Internet network numbers may be specified in one of the following forms:
2122
2123            a.b.c.d/bits
2124            a.b.c.d
2125            a.b.c
2126            a.b
2127            a
2128
2129      When four parts are specified, each is interpreted as a byte of data and
2130      assigned, from left to right, to the four bytes of an Internet network
2131      number.  Note that when an Internet network number is viewed as a 32-bit
2132      integer quantity on a system that uses little-endian byte order (such as
2133      the Intel 386, 486, and Pentium processors) the bytes referred to above
2134      appear as ``d.c.b.a''.  That is, little-endian bytes are ordered from
2135      right to left.
2136
2137      When a three part number is specified, the last part is interpreted as a
2138      16-bit quantity and placed in the rightmost two bytes of the Internet
2139      network number.  This makes the three part number format convenient for
2140      specifying Class B network numbers as ``128.net.host''.
2141
2142      When a two part number is supplied, the last part is interpreted as a
2143      24-bit quantity and placed in the rightmost three bytes of the Internet
2144      network number.  This makes the two part number format convenient for
2145      specifying Class A network numbers as ``net.host''.
2146
2147      When only one part is given, the value is stored directly in the Internet
2148      network number without any byte rearrangement.
2149
2150      All numbers supplied as ``parts'' in a '.' notation may be decimal,
2151      octal, or hexadecimal, as specified in the C language (i.e., a leading 0x
2152      or 0X implies hexadecimal; otherwise, a leading 0 implies octal; other-
2153      wise, the number is interpreted as decimal).
2154
2155 SEE ALSO
2156      byteorder(3), inet(3), networks(5)
2157
2158 HISTORY
2159      The inet_net_ntop and inet_net_pton functions first appeared in BIND
2160      4.9.4.
2161
2162 BSD                              June 18, 1997                             BSD
2163     </screen>
2164   </sect1>
2165
2166   <sect1 id="net-common-tcpip-manpages-ipx">
2167     <title>ipx</title>
2168     <screen>
2169 IPX(3)                   BSD Library Functions Manual                   IPX(3)
2170
2171 NAME
2172      ipx_addr, ipx_ntoa - IPX address conversion routines
2173
2174 SYNOPSIS
2175      #include &lt;sys/types.h>
2176      #include &lt;netipx/ipx.h>
2177
2178      struct ipx_addr
2179      ipx_addr(const char *cp);
2180
2181      char *
2182      ipx_ntoa(struct ipx_addr ipx);
2183
2184 DESCRIPTION
2185      The routine ipx_addr() interprets character strings representing IPX
2186      addresses, returning binary information suitable for use in system calls.
2187      The routine ipx_ntoa() takes IPX addresses and returns ASCII strings rep-
2188      resenting the address in a notation in common use:
2189
2190            &lt;network number>.&lt;host number>.&lt;port number>
2191
2192      Trailing zero fields are suppressed, and each number is printed in hex-
2193      adecimal, in a format suitable for input to ipx_addr().  Any fields lack-
2194      ing super-decimal digits will have a trailing 'H' appended.
2195
2196      An effort has been made to ensure that ipx_addr() be compatible with most
2197      formats in common use.  It will first separate an address into 1 to 3
2198      fields using a single delimiter chosen from period ('.'), colon (':'), or
2199      pound-sign ('#').  Each field is then examined for byte separators (colon
2200      or period).  If there are byte separators, each subfield separated is
2201      taken to be a small hexadecimal number, and the entirety is taken as a
2202      network-byte-ordered quantity to be zero extended in the high-network-
2203      order bytes.  Next, the field is inspected for hyphens, in which case the
2204      field is assumed to be a number in decimal notation with hyphens separat-
2205      ing the millenia.  Next, the field is assumed to be a number: It is
2206      interpreted as hexadecimal if there is a leading '0x' (as in C), a trail-
2207      ing 'H' (as in Mesa), or there are any super-decimal digits present.  It
2208      is interpreted as octal is there is a leading '0' and there are no super-
2209      octal digits.  Otherwise, it is converted as a decimal number.
2210
2211 RETURN VALUES
2212      None.  (See BUGS.)
2213
2214 SEE ALSO
2215      ns(4), hosts(5), networks(5)
2216
2217 HISTORY
2218      The precursor ns_addr() and ns_ntoa() functions appeared in 4.3BSD.
2219
2220 BUGS
2221      The string returned by ipx_ntoa() resides in a static memory area.  The
2222      function ipx_addr() should diagnose improperly formed input, and there
2223      should be an unambiguous way to recognize this.
2224
2225 BSD                              June 4, 1993                              BSD
2226     </screen>
2227   </sect1>
2228
2229   <sect1 id="net-common-tcpip-manpages-iso-addr">
2230     <title>iso_addr</title>
2231     <screen>
2232 ISO_ADDR(3)              BSD Library Functions Manual              ISO_ADDR(3)
2233
2234 NAME
2235      iso_addr, iso_ntoa - network address conversion routines for Open System
2236      Interconnection
2237
2238 SYNOPSIS
2239      #include &lt;sys/types.h>
2240      #include &lt;netiso/iso.h>
2241
2242      struct iso_addr *
2243      iso_addr(char *cp);
2244
2245      char *
2246      iso_ntoa(struct iso_addr *isoa);
2247
2248 DESCRIPTION
2249      The routine iso_addr() interprets character strings representing OSI
2250      addresses, returning binary information suitable for use in system calls.
2251      The routine iso_ntoa() takes OSI addresses and returns ASCII strings rep-
2252      resenting NSAPs (network service access points) in a notation inverse to
2253      that accepted by iso_addr().
2254
2255      Unfortunately, no universal standard exists for representing OSI network
2256      addresses.
2257
2258      The format employed by iso_addr() is a sequence of hexadecimal ``digits''
2259      (optionally separated by periods), of the form:
2260
2261            &lt;hex digits>.&lt;hex digits>.&lt;hex digits>
2262
2263      Each pair of hexadecimal digits represents a byte with the leading digit
2264      indicating the higher-ordered bits.  A period following an even number of
2265      bytes has no effect (but may be used to increase legibility).  A period
2266      following an odd number of bytes has the effect of causing the byte of
2267      address being translated to have its higher order bits filled with zeros.
2268
2269 RETURN VALUES
2270      iso_ntoa() always returns a null terminated string.  iso_addr() always
2271      returns a pointer to a struct iso_addr.  (See BUGS.)
2272
2273 SEE ALSO
2274      iso(4)
2275
2276 HISTORY
2277      The iso_addr() and iso_ntoa() functions appeared in 4.3BSD-Reno.
2278
2279 BUGS
2280      The returned values reside in a static memory area.
2281
2282      The function iso_addr() should diagnose improperly formed input, and
2283      there should be an unambiguous way to recognize this.
2284
2285 BSD                              June 4, 1993                              BSD
2286     </screen>
2287   </sect1>
2288
2289   <sect1 id="net-common-tcpip-manpages-link-addr">
2290     <title>link_addr</title>
2291     <screen>
2292 LINK_ADDR(3)             BSD Library Functions Manual             LINK_ADDR(3)
2293
2294 NAME
2295      link_addr, link_ntoa - elementary address specification routines for link
2296      level access
2297
2298 SYNOPSIS
2299      #include &lt;sys/types.h>
2300      #include &lt;sys/socket.h>
2301      #include &lt;net/if_dl.h>
2302
2303      void
2304      link_addr(const char *addr, struct sockaddr_dl *sdl);
2305
2306      char *
2307      link_ntoa(const struct sockaddr_dl *sdl);
2308
2309 DESCRIPTION
2310      The link_addr() function interprets character strings representing link-
2311      level addresses, returning binary information suitable for use in system
2312      calls.  link_ntoa() takes a link-level address and returns an ASCII
2313      string representing some of the information present, including the link
2314      level address itself, and the interface name or number, if present.  This
2315      facility is experimental and is still subject to change.
2316
2317      For link_addr(), the string addr may contain an optional network inter-
2318      face identifier of the form ``name unit-number'', suitable for the first
2319      argument to ifconfig(8), followed in all cases by a colon and an inter-
2320      face address in the form of groups of hexadecimal digits separated by
2321      periods.  Each group represents a byte of address; address bytes are
2322      filled left to right from low order bytes through high order bytes.
2323
2324      Thus le0:8.0.9.13.d.30 represents an Ethernet address to be transmitted
2325      on the first Lance Ethernet interface.
2326
2327 RETURN VALUES
2328      link_ntoa() always returns a null-terminated string.  link_addr() has no
2329      return value.  (See BUGS.)
2330
2331 SEE ALSO
2332      iso(4), ifconfig(8)
2333
2334 HISTORY
2335      The link_addr() and link_ntoa() functions appeared in 4.3BSD-Reno.
2336
2337 BUGS
2338      The returned values for link_ntoa reside in a static memory area.
2339
2340      The function link_addr() should diagnose improperly formed input, and
2341      there should be an unambiguous way to recognize this.
2342
2343      If the sdl_len field of the link socket address sdl is 0, link_ntoa()
2344      will not insert a colon before the interface address bytes.  If this
2345      translated address is given to link_addr() without inserting an initial
2346      colon, the latter will not interpret it correctly.
2347
2348 BSD                              July 28, 1993                             BSD
2349     </screen>
2350   </sect1>
2351
2352   <sect1 id="net-common-tcpip-manpages-net-addrcmp">
2353     <title>net_addrcmp</title>
2354     <screen>
2355 NET_ADDRCMP(3)           BSD Library Functions Manual           NET_ADDRCMP(3)
2356
2357 NAME
2358      net_addrcmp - compare socket address structures
2359
2360 SYNOPSIS
2361      #include &lt;netdb.h>
2362
2363      int
2364      net_addrcmp(struct sockaddr *sa1, struct sockaddr *sa2);
2365
2366 DESCRIPTION
2367      The net_addrcmp() function compares two socket address structures, sa1
2368      and sa2.
2369
2370 RETURN VALUES
2371      If sa1 and sa2 are for the same address, net_addrcmp() returns 0.
2372
2373      The sa_len fields are compared first.  If they do not match,
2374      net_addrcmp() returns -1 or 1 if sa1->sa_len is less than or greater than
2375      sa2->sa_len, respectively.
2376
2377      Next, the sa_family members are compared.  If they do not match,
2378      net_addrcmp() returns -1 or 1 if sa1->sa_family is less than or greater
2379      than sa2->sa_family, respectively.
2380
2381      Lastly, if each socket address structure's sa_len and sa_family fields
2382      match, the protocol-specific data (the sa_data field) is compared.  If
2383      there's a match, both sa1 and sa2 must refer to the same address, and 0
2384      is returned; otherwise, a value >0 or &lt;0 is returned.
2385
2386 HISTORY
2387      A net_addrcmp() function was added in OpenBSD 2.5.
2388
2389 BSD                              July 3, 1999                              BSD
2390     </screen>
2391   </sect1>
2392
2393   <sect1 id="net-common-tcpip-manpages-ns">
2394     <title>ns</title>
2395     <screen>
2396 NS(3)                    BSD Library Functions Manual                    NS(3)
2397
2398 NAME
2399      ns_addr, ns_ntoa - Xerox NS(tm) address conversion routines
2400
2401 SYNOPSIS
2402      #include &lt;sys/types.h>
2403      #include &lt;netns/ns.h>
2404
2405      struct ns_addr
2406      ns_addr(char *cp);
2407
2408      char *
2409      ns_ntoa(struct ns_addr ns);
2410
2411 DESCRIPTION
2412      The routine ns_addr() interprets character strings representing XNS
2413      addresses, returning binary information suitable for use in system calls.
2414      The routine ns_ntoa() takes XNS addresses and returns ASCII strings rep-
2415      resenting the address in a notation in common use in the Xerox Develop-
2416      ment Environment:
2417
2418            &lt;network number>.&lt;host number>.&lt;port number>
2419
2420      Trailing zero fields are suppressed, and each number is printed in hex-
2421      adecimal, in a format suitable for input to ns_addr().  Any fields lack-
2422      ing super-decimal digits will have a trailing 'H' appended.
2423
2424      Unfortunately, no universal standard exists for representing XNS
2425      addresses.  An effort has been made to ensure that ns_addr() be compati-
2426      ble with most formats in common use.  It will first separate an address
2427      into 1 to 3 fields using a single delimiter chosen from period ('.'),
2428      colon (':'), or pound-sign '#'.  Each field is then examined for byte
2429      separators (colon or period).  If there are byte separators, each sub-
2430      field separated is taken to be a small hexadecimal number, and the
2431      entirety is taken as a network-byte-ordered quantity to be zero extended
2432      in the high-network-order bytes.  Next, the field is inspected for
2433      hyphens, in which case the field is assumed to be a number in decimal
2434      notation with hyphens separating the millenia.  Next, the field is
2435      assumed to be a number: It is interpreted as hexadecimal if there is a
2436      leading '0x' (as in C), a trailing 'H' (as in Mesa), or there are any
2437      super-decimal digits present.  It is interpreted as octal is there is a
2438      leading '0' and there are no super-octal digits.  Otherwise, it is con-
2439      verted as a decimal number.
2440
2441 RETURN VALUES
2442      None.  (See BUGS.)
2443
2444 SEE ALSO
2445      hosts(5), networks(5)
2446
2447 HISTORY
2448      The ns_addr() and ns_toa() functions appeared in 4.3BSD.
2449
2450 BUGS
2451      The string returned by ns_ntoa() resides in a static memory area.  The
2452      function ns_addr() should diagnose improperly formed input, and there
2453      should be an unambiguous way to recognize this.
2454
2455 BSD                              June 4, 1993                              BSD
2456     </screen>
2457   </sect1>
2458
2459   <sect1 id="net-common-tcpip-manpages-resolver">
2460     <title>resolver</title>
2461     <screen>
2462 RESOLVER(3)              BSD Library Functions Manual              RESOLVER(3)
2463
2464 NAME
2465      res_query, res_search, res_mkquery, res_send, res_init, dn_comp,
2466      dn_expand - resolver routines
2467
2468 SYNOPSIS
2469      #include &lt;sys/types.h>
2470      #include &lt;netinet/in.h>
2471      #include &lt;arpa/nameser.h>
2472      #include &lt;resolv.h>
2473
2474      int
2475      res_query(char *dname, int class, int type, u_char *answer, int anslen);
2476
2477      int
2478      res_search(char *dname, int class, int type, u_char *answer, int anslen);
2479
2480      int
2481      res_mkquery(int op, char *dname, int class, int type, char *data,
2482              int datalen, struct rrec *newrr, char *buf, int buflen);
2483
2484      int
2485      res_send(char *msg, int msglen, char *answer, int anslen);
2486
2487      int
2488      res_init(void);
2489
2490      int
2491      dn_comp(char *exp_dn, char *comp_dn, int length, char **dnptrs,
2492              char **lastdnptr);
2493
2494      int
2495      dn_expand(u_char *msg, u_char *eomorig, u_char *comp_dn, u_char *exp_dn,
2496              int length);
2497
2498 DESCRIPTION
2499      These routines are used for making, sending, and interpreting query and
2500      reply messages with Internet domain name servers.
2501
2502      Global configuration and state information that is used by the resolver
2503      routines is kept in the structure _res.  Most of the values have reason-
2504      able defaults and can be ignored.  Options stored in _res.options are
2505      defined in &lt;resolv.h> and are as follows.  Options are stored as a simple
2506      bit mask containing the bitwise OR of the options enabled.
2507
2508      RES_INIT       True if the initial name server address and default domain
2509                     name are initialized (i.e., res_init() has been called).
2510
2511      RES_DEBUG      Print debugging messages.
2512
2513      RES_AAONLY     Accept authoritative answers only.  With this option,
2514                     res_send() should continue until it finds an authoritative
2515                     answer or finds an error.  Currently this is not imple-
2516                     mented.
2517
2518      RES_USEVC      Use TCP connections for queries instead of UDP datagrams.
2519
2520      RES_STAYOPEN   Used with RES_USEVC to keep the TCP connection open
2521                     between queries.  This is useful only in programs that
2522                     regularly do many queries.  UDP should be the normal mode
2523                     used.
2524
2525      RES_IGNTC      Unused currently (ignore truncation errors, i.e., don't
2526                     retry with TCP).
2527
2528      RES_RECURSE    Set the recursion-desired bit in queries.  This is the
2529                     default.  (res_send() does not do iterative queries and
2530                     expects the name server to handle recursion.)
2531
2532      RES_DEFNAMES   If set, res_search() will append the default domain name
2533                     to single-component names (those that do not contain a
2534                     dot).  This option is enabled by default.
2535
2536      RES_DNSRCH     If this option is set, res_search() will search for host
2537                     names in the current domain and in parent domains; see
2538                     hostname(7).  This is used by the standard host lookup
2539                     routine gethostbyname(3).  This option is enabled by
2540                     default.
2541
2542      RES_USE_INET6  Enables support for IPv6-only applications.  This causes
2543                     IPv4 addresses to be returned as an IPv4 mapped address.
2544                     For example, 10.1.1.1 will be returned as ::ffff:10.1.1.1.
2545                     The option is not meaningful on OpenBSD.
2546
2547      The res_init() routine reads the configuration file (if any; see
2548      resolv.conf(5)) to get the default domain name, search list, and the
2549      Internet address of the local name server(s).  If no server is config-
2550      ured, the host running the resolver is tried.  The current domain name is
2551      defined by the hostname if not specified in the configuration file; it
2552      can be overridden by the environment variable LOCALDOMAIN.  This environ-
2553      ment variable may contain several blank-separated tokens if you wish to
2554      override the search list on a per-process basis.  This is similar to the
2555      search command in the configuration file.  Another environment variable
2556      RES_OPTIONS can be set to override certain internal resolver options
2557      which are otherwise set by changing fields in the _res structure or are
2558      inherited from the configuration file's options command.  The syntax of
2559      the RES_OPTIONS environment variable is explained in resolv.conf(5).
2560      Initialization normally occurs on the first call to one of the following
2561      routines.
2562
2563      The res_query() function provides an interface to the server query mecha-
2564      nism.  It constructs a query, sends it to the local server, awaits a
2565      response, and makes preliminary checks on the reply.  The query requests
2566      information of the specified type and class for the specified fully qual-
2567      ified domain name dname.  The reply message is left in the answer buffer
2568      with length anslen supplied by the caller.
2569
2570      The res_search() routine makes a query and awaits a response like
2571      res_query(), but in addition, it implements the default and search rules
2572      controlled by the RES_DEFNAMES and RES_DNSRCH options.  It returns the
2573      first successful reply.
2574
2575      The remaining routines are lower-level routines used by res_query().  The
2576      res_mkquery() function constructs a standard query message and places it
2577      in buf.  It returns the size of the query, or -1 if the query is larger
2578      than buflen.  The query type op is usually QUERY, but can be any of the
2579      query types defined in &lt;arpa/nameser.h>.  The domain name for the query
2580      is given by dname.  newrr is currently unused but is intended for making
2581      update messages.
2582
2583      The res_send() routine sends a pre-formatted query and returns an answer.
2584      It will call res_init() if RES_INIT is not set, send the query to the
2585      local name server, and handle timeouts and retries.  The length of the
2586      reply message is returned, or -1 if there were errors.
2587
2588      The dn_comp() function compresses the domain name exp_dn and stores it in
2589      comp_dn.  The size of the compressed name is returned or -1 if there were
2590      errors.  The size of the array pointed to by comp_dn is given by length.
2591      The compression uses an array of pointers dnptrs to previously compressed
2592      names in the current message.  The first pointer points to the beginning
2593      of the message and the list ends with NULL.  The limit to the array is
2594      specified by lastdnptr.  A side effect of dn_comp() is to update the list
2595      of pointers for labels inserted into the message as the name is com-
2596      pressed.  If dnptr is NULL, names are not compressed.  If lastdnptr is
2597      NULL, the list of labels is not updated.
2598
2599      The dn_expand() entry expands the compressed domain name comp_dn to a
2600      full domain name The compressed name is contained in a query or reply
2601      message; msg is a pointer to the beginning of the message.  The uncom-
2602      pressed name is placed in the buffer indicated by exp_dn which is of size
2603      length.  The size of compressed name is returned or -1 if there was an
2604      error.
2605
2606 FILES
2607      /etc/resolv.conf configuration file see resolv.conf(5).
2608
2609 SEE ALSO
2610      gethostbyname(3), resolv.conf(5), hostname(7), named(8)
2611
2612      RFC1032, RFC1033, RFC1034, RFC1035, RFC1535, RFC974
2613
2614      Name Server Operations Guide for BIND.
2615
2616 HISTORY
2617      The res_query function appeared in 4.3BSD.
2618
2619 BSD                              June 4, 1993                              BSD
2620     </screen>
2621   </sect1>
2622
2623   <sect1 id="net-common-tcpip-manpages-accept">
2624     <title>accept</title>
2625     <screen>
2626 ACCEPT(2)                   BSD System Calls Manual                  ACCEPT(2)
2627
2628 NAME
2629      accept - accept a connection on a socket
2630
2631 SYNOPSIS
2632      #include &lt;sys/types.h>
2633      #include &lt;sys/socket.h>
2634
2635      int
2636      accept(int s, struct sockaddr *addr, socklen_t *addrlen);
2637
2638 DESCRIPTION
2639      The argument s is a socket that has been created with socket(2), bound to
2640      an address with bind(2), and is listening for connections after a
2641      listen(2).  The accept() argument extracts the first connection request
2642      on the queue of pending connections, creates a new socket with the same
2643      properties of s, and allocates a new file descriptor for the socket.  If
2644      no pending connections are present on the queue, and the socket is not
2645      marked as non-blocking, accept() blocks the caller until a connection is
2646      present.  If the socket is marked non-blocking and no pending connections
2647      are present on the queue, accept() returns an error as described below.
2648      The accepted socket may not be used to accept more connections.  The
2649      original socket s remains open.
2650
2651      The argument addr is a result parameter that is filled in with the
2652      address of the connecting entity as known to the communications layer.
2653      The exact format of the addr parameter is determined by the domain in
2654      which the communication is occurring.  The addrlen is a value-result
2655      parameter; it should initially contain the amount of space pointed to by
2656      addr; on return it will contain the actual length (in bytes) of the
2657      address returned.  This call is used with connection-based socket types,
2658      currently with SOCK_STREAM.
2659
2660      It is possible to select(2) or poll(2) a socket for the purposes of doing
2661      an accept() by selecting it for read.
2662
2663      For certain protocols which require an explicit confirmation, such as ISO
2664      or DATAKIT, accept() can be thought of as merely dequeuing the next con-
2665      nection request and not implying confirmation.  Confirmation can be
2666      implied by a normal read or write on the new file descriptor, and rejec-
2667      tion can be implied by closing the new socket.
2668
2669      One can obtain user connection request data without confirming the con-
2670      nection by issuing a recvmsg(2) call with an msg_iovlen of 0 and a non-
2671      zero msg_controllen, or by issuing a getsockopt(2) request.  Similarly,
2672      one can provide user connection rejection information by issuing a
2673      sendmsg(2) call with providing only the control information, or by call-
2674      ing setsockopt(2).
2675
2676 RETURN VALUES
2677      The call returns -1 on error.  If it succeeds, it returns a non-negative
2678      integer that is a descriptor for the accepted socket.
2679
2680 ERRORS
2681      The accept() will fail if:
2682
2683      [EBADF]            The descriptor is invalid.
2684
2685      [ENOTSOCK]         The descriptor references a file, not a socket.
2686
2687      [EOPNOTSUPP]       The referenced socket is not of type SOCK_STREAM.
2688
2689      [EINVAL]           The referenced socket is not listening for connections
2690                         (that is, listen(2) has not yet been called).
2691
2692      [EFAULT]           The addr parameter is not in a writable part of the
2693                         user address space.
2694
2695      [EWOULDBLOCK]      The socket is marked non-blocking and no connections
2696                         are present to be accepted.
2697
2698      [EMFILE]           The per-process descriptor table is full.
2699
2700      [ENFILE]           The system file table is full.
2701
2702      [ECONNABORTED]     A connection has been aborted.
2703
2704 SEE ALSO
2705      bind(2), connect(2), listen(2), poll(2), select(2), poll(2), socket(2)
2706
2707 HISTORY
2708      The accept() function appeared in 4.2BSD.
2709
2710 BSD                            February 15, 1999                           BSD
2711     </screen>
2712   </sect1>
2713
2714   <sect1 id="net-common-tcpip-manpages-bind">
2715     <title>bind</title>
2716     <screen>
2717 BIND(2)                     BSD System Calls Manual                    BIND(2)
2718
2719 NAME
2720      bind - bind a name to a socket
2721
2722 SYNOPSIS
2723      #include &lt;sys/types.h>
2724      #include &lt;sys/socket.h>
2725
2726      int
2727      bind(int s, const struct sockaddr *name, socklen_t namelen);
2728
2729 DESCRIPTION
2730      bind() assigns a name to an unnamed socket.  When a socket is created
2731      with socket(2) it exists in a name space (address family) but has no name
2732      assigned.  bind() requests that name be assigned to the socket.
2733
2734 NOTES
2735      Binding a name in the UNIX domain creates a socket in the file system
2736      that must be deleted by the caller when it is no longer needed (using
2737      unlink(2)).
2738
2739      The rules used in name binding vary between communication domains.  Con-
2740      sult the manual entries in section 4 for detailed information.
2741
2742 RETURN VALUES
2743      If the bind is successful, a 0 value is returned.  A return value of -1
2744      indicates an error, which is further specified in the global errno.
2745
2746 ERRORS
2747      The bind() call will fail if:
2748
2749      [EBADF]            S is not a valid descriptor.
2750
2751      [ENOTSOCK]         S is not a socket.
2752
2753      [EADDRNOTAVAIL]    The specified address is not available from the local
2754                         machine.
2755
2756      [EADDRINUSE]       The specified address is already in use.
2757
2758      [EINVAL]           The socket is already bound to an address.
2759
2760      [EINVAL]           The family of the socket and that requested in
2761                         name->sa_family are not equivalent.
2762
2763      [EACCES]           The requested address is protected, and the current
2764                         user has inadequate permission to access it.
2765
2766      [EFAULT]           The name parameter is not in a valid part of the user
2767                         address space.
2768
2769      The following errors are specific to binding names in the UNIX domain.
2770
2771      [ENOTDIR]          A component of the path prefix is not a directory.
2772
2773      [ENAMETOOLONG]     A component of a pathname exceeded {NAME_MAX} charac-
2774                         ters, or an entire path name exceeded {PATH_MAX} char-
2775                         acters.
2776
2777      [ENOENT]           A prefix component of the path name does not exist.
2778
2779      [ELOOP]            Too many symbolic links were encountered in translat-
2780                         ing the pathname.
2781
2782      [EIO]              An I/O error occurred while making the directory entry
2783                         or allocating the inode.
2784
2785      [EROFS]            The name would reside on a read-only file system.
2786
2787      [EISDIR]           An empty pathname was specified.
2788
2789 SEE ALSO
2790      connect(2), getsockname(2), listen(2), socket(2)
2791
2792 HISTORY
2793      The bind() function call appeared in 4.2BSD.
2794
2795 BSD                            February 15, 1999                           BSD
2796     </screen>
2797   </sect1>
2798
2799   <sect1 id="net-common-tcpip-manpages-connect">
2800     <title>connect</title>
2801     <screen>
2802 CONNECT(2)                  BSD System Calls Manual                 CONNECT(2)
2803
2804 NAME
2805      connect - initiate a connection on a socket
2806
2807 SYNOPSIS
2808      #include &lt;sys/types.h>
2809      #include &lt;sys/socket.h>
2810
2811      int
2812      connect(int s, const struct sockaddr *name, socklen_t namelen);
2813
2814 DESCRIPTION
2815      The parameter s is a socket.  If it is of type SOCK_DGRAM, this call
2816      specifies the peer with which the socket is to be associated; this
2817      address is that to which datagrams are to be sent, and the only address
2818      from which datagrams are to be received.  If the socket is of type
2819      SOCK_STREAM, this call attempts to make a connection to another socket.
2820      The other socket is specified by name, which is an address in the commu-
2821      nications space of the socket.  Each communications space interprets the
2822      name parameter in its own way.  Generally, stream sockets may success-
2823      fully connect() only once; datagram sockets may use connect() multiple
2824      times to change their association.  Datagram sockets may dissolve the
2825      association by connecting to an invalid address, such as a null address.
2826
2827 RETURN VALUES
2828      If the connection or binding succeeds, 0 is returned.  Otherwise a -1 is
2829      returned, and a more specific error code is stored in errno.
2830
2831 ERRORS
2832      The connect() call fails if:
2833
2834      [EBADF]            S is not a valid descriptor.
2835
2836      [ENOTSOCK]         S is a descriptor for a file, not a socket.
2837
2838      [EADDRNOTAVAIL]    The specified address is not available on this
2839                         machine.
2840
2841      [EAFNOSUPPORT]     Addresses in the specified address family cannot be
2842                         used with this socket.
2843
2844      [EISCONN]          The socket is already connected.
2845
2846      [ETIMEDOUT]        Connection establishment timed out without establish-
2847                         ing a connection.
2848
2849      [EINVAL]           A TCP connection with a local broadcast, the all-ones
2850                         or a multicast address as the peer was attempted.
2851
2852      [ECONNREFUSED]     The attempt to connect was forcefully rejected.
2853
2854      [EINTR]            A connect was interrupted before it succeeded by the
2855                         delivery of a signal.
2856
2857      [ENETUNREACH]      The network isn't reachable from this host.
2858
2859      [EADDRINUSE]       The address is already in use.
2860
2861      [EFAULT]           The name parameter specifies an area outside the pro-
2862                         cess address space.
2863
2864      [EINPROGRESS]      The socket is non-blocking and the connection cannot
2865                         be completed immediately.  It is possible to select(2)
2866                         or poll(2) for completion by selecting the socket for
2867                         writing, and also use getsockopt(2) with SO_ERROR to
2868                         check for error conditions.
2869
2870      [EALREADY]         The socket is non-blocking and a previous connection
2871                         attempt has not yet been completed.
2872
2873      The following errors are specific to connecting names in the UNIX domain.
2874      These errors may not apply in future versions of the UNIX IPC domain.
2875
2876      [ENOTDIR]          A component of the path prefix is not a directory.
2877
2878      [ENAMETOOLONG]     A component of a pathname exceeded {NAME_MAX} charac-
2879                         ters, or an entire path name exceeded {PATH_MAX} char-
2880                         acters.
2881
2882      [ENOENT]           The named socket does not exist.
2883
2884      [EACCES]           Search permission is denied for a component of the
2885                         path prefix.
2886
2887      [EACCES]           Write access to the named socket is denied.
2888
2889      [ELOOP]            Too many symbolic links were encountered in translat-
2890                         ing the pathname.
2891
2892 SEE ALSO
2893      accept(2), getsockname(2), getsockopt(2), poll(2), select(2), socket(2)
2894
2895 HISTORY
2896      The connect() function call appeared in 4.2BSD.
2897
2898 BSD                            February 15, 1999                           BSD
2899     </screen>
2900   </sect1>
2901
2902   <sect1 id="net-common-tcpip-manpages-getpeername">
2903     <title>getpeername</title>
2904     <screen>
2905 GETPEERNAME(2)              BSD System Calls Manual             GETPEERNAME(2)
2906
2907 NAME
2908      getpeername - get name of connected peer
2909
2910 SYNOPSIS
2911      #include &lt;sys/types.h>
2912      #include &lt;sys/socket.h>
2913
2914      int
2915      getpeername(int s, struct sockaddr *name, socklen_t *namelen);
2916
2917 DESCRIPTION
2918      getpeername() returns the address information of the peer connected to
2919      socket s.  One common use occurs when a process inherits an open socket,
2920      such as TCP servers forked from inetd(8).  In this scenario,
2921      getpeername() is used to determine the connecting client's IP address.
2922
2923      getpeername() takes three parameters:
2924
2925      s Contains the file descriptor of the socket whose peer should be looked
2926      up.
2927
2928      name Points to a sockaddr structure that will hold the address informa-
2929      tion for the connected peer.  Normal use requires one to use a structure
2930      specific to the protocol family in use, such as sockaddr_in (IPv4) or
2931      sockaddr_in6 (IPv6), cast to a (struct sockaddr *).
2932
2933      For greater portability, especially with the newer protocol families, the
2934      new struct sockaddr_storage should be used.  sockaddr_storage is large
2935      enough to hold any of the other sockaddr_* variants.  On return, it can
2936      be cast to the correct sockaddr type, based the protocol family contained
2937      in its ss_family field.
2938
2939      namelen Indicates the amount of space pointed to by name, in bytes.
2940
2941      If address information for the local end of the socket is required, the
2942      getsockname(2) function should be used instead.
2943
2944      If name does not point to enough space to hold the entire socket address,
2945      the result will be truncated to namelen bytes.
2946
2947 RETURN VALUES
2948      If the call succeeds, a 0 is returned and namelen is set to the actual
2949      size of the socket address returned in name.  Otherwise, errno is set and
2950      a value of -1 is returned.
2951
2952 ERRORS
2953      On failure, errno is set to one of the following:
2954
2955      [EBADF]            The argument s is not a valid descriptor.
2956
2957      [ENOTSOCK]         The argument s is a file, not a socket.
2958
2959      [ENOTCONN]         The socket is not connected.
2960
2961      [ENOBUFS]          Insufficient resources were available in the system to
2962                         perform the operation.
2963
2964      [EFAULT]           The name parameter points to memory not in a valid
2965                         part of the process address space.
2966
2967 SEE ALSO
2968      accept(2), bind(2), getsockname(2), getpeereid(2), socket(2)
2969
2970 HISTORY
2971      The getpeername() function call appeared in 4.2BSD.
2972
2973 BSD                              July 17, 1999                             BSD
2974     </screen>
2975   </sect1>
2976
2977   <sect1 id="net-common-tcpip-manpages-getsockname">
2978     <title>getsockname</title>
2979     <screen>
2980 GETSOCKNAME(2)              BSD System Calls Manual             GETSOCKNAME(2)
2981
2982 NAME
2983      getsockname - get socket name
2984
2985 SYNOPSIS
2986      #include &lt;sys/types.h>
2987      #include &lt;sys/socket.h>
2988
2989      int
2990      getsockname(int s, struct sockaddr *name, socklen_t *namelen);
2991
2992 DESCRIPTION
2993      getsockname() returns the locally bound address information for a speci-
2994      fied socket.
2995
2996      Common uses of this function are as follows:
2997
2998      o   When bind(2) is called with a port number of 0 (indicating the kernel
2999          should pick an ephemeral port) getsockname() is used to retrieve the
3000          kernel-assigned port number.
3001
3002      o   When a process calls bind(2) on a wildcard IP address, getsockname()
3003          is used to retrieve the local IP address for the connection.
3004
3005      o   When a function wishes to know the address family of a socket,
3006          getsockname() can be used.
3007
3008      getsockname() takes three parameters:
3009
3010      s, Contains the file desriptor for the socket to be looked up.
3011
3012      name points to a sockaddr structure which will hold the resulting address
3013      information.  Normal use requires one to use a structure specific to the
3014      protocol family in use, such as sockaddr_in (IPv4) or sockaddr_in6
3015      (IPv6), cast to a (struct sockaddr *).
3016
3017      For greater portability (such as newer protocol families) the new struc-
3018      ture sockaddr_storage exists.  sockaddr_storage is large enough to hold
3019      any of the other sockaddr_* variants.  On return, it should be cast to
3020      the correct sockaddr type, according to the current protocol family.
3021
3022      namelen Indicates the amount of space pointed to by name, in bytes.  Upon
3023      return, namelen is set to the actual size of the returned address infor-
3024      mation.
3025
3026      If the address of the destination socket for a given socket connection is
3027      needed, the getpeername(2) function should be used instead.
3028
3029      If name does not point to enough space to hold the entire socket address,
3030      the result will be truncated to namelen bytes.
3031
3032 RETURN VALUES
3033      On success, getsockname() returns a 0, and namelen is set to the actual
3034      size of the socket address returned in name.  Otherwise, errno is set,
3035      and a value of -1 is returned.
3036
3037 ERRORS
3038      If getsockname() fails, errno is set to one of the following:
3039
3040      [EBADF]            The argument s is not a valid descriptor.
3041
3042      [ENOTSOCK]         The argument s is a file, not a socket.
3043
3044      [ENOBUFS]          Insufficient resources were available in the system to
3045                         perform the operation.
3046
3047      [EFAULT]           The name parameter points to memory not in a valid
3048                         part of the process address space.
3049
3050 SEE ALSO
3051      accept(2), bind(2), getpeername(2), getpeereid(2), socket(2)
3052
3053 BUGS
3054      Names bound to sockets in the UNIX domain are inaccessible; getsockname
3055      returns a zero length name.
3056
3057 HISTORY
3058      The getsockname() function call appeared in 4.2BSD.
3059
3060 BSD                              July 17, 1999                             BSD
3061     </screen>
3062   </sect1>
3063
3064   <sect1 id="net-common-tcpip-manpages-getsockopt">
3065     <title>getsockopt</title>
3066     <screen>
3067 GETSOCKOPT(2)               BSD System Calls Manual              GETSOCKOPT(2)
3068
3069 NAME
3070      getsockopt, setsockopt - get and set options on sockets
3071
3072 SYNOPSIS
3073      #include &lt;sys/types.h>
3074      #include &lt;sys/socket.h>
3075
3076      int
3077      getsockopt(int s, int level, int optname, void *optval,
3078              socklen_t *optlen);
3079
3080      int
3081      setsockopt(int s, int level, int optname, const void *optval,
3082              socklen_t optlen);
3083
3084 DESCRIPTION
3085      getsockopt() and setsockopt() manipulate the options associated with a
3086      socket.  Options may exist at multiple protocol levels; they are always
3087      present at the uppermost ``socket'' level.
3088
3089      When manipulating socket options the level at which the option resides
3090      and the name of the option must be specified.  To manipulate options at
3091      the socket level, level is specified as SOL_SOCKET.  To manipulate
3092      options at any other level the protocol number of the appropriate proto-
3093      col controlling the option is supplied.  For example, to indicate that an
3094      option is to be interpreted by the TCP protocol, level should be set to
3095      the protocol number of TCP; see getprotoent(3).
3096
3097      The parameters optval and optlen are used to access option values for
3098      setsockopt().  For getsockopt() they identify a buffer in which the value
3099      for the requested option(s) are to be returned.  For getsockopt(), optlen
3100      is a value-result parameter, initially containing the size of the buffer
3101      pointed to by optval, and modified on return to indicate the actual size
3102      of the value returned.  If no option value is to be supplied or returned,
3103      optval may be NULL.
3104
3105      optname and any specified options are passed uninterpreted to the appro-
3106      priate protocol module for interpretation.  The include file
3107      &lt;sys/socket.h> contains definitions for socket level options, described
3108      below.  Options at other protocol levels vary in format and name; consult
3109      the appropriate entries in section 4 of the manual.
3110
3111      Most socket-level options utilize an int parameter for optval.  For
3112      setsockopt(), the parameter should be non-zero to enable a boolean
3113      option, or zero if the option is to be disabled.  SO_LINGER uses a struct
3114      linger parameter, defined in &lt;sys/socket.h>, which specifies the desired
3115      state of the option and the linger interval (see below).  SO_SNDTIMEO and
3116      SO_RCVTIMEO use a struct timeval parameter, defined in &lt;sys/time.h>.
3117
3118      The following options are recognized at the socket level.  Except as
3119      noted, each may be examined with getsockopt() and set with setsockopt().
3120
3121            SO_DEBUG        enables recording of debugging information
3122            SO_REUSEADDR    enables local address reuse
3123            SO_REUSEPORT    enables duplicate address and port bindings
3124            SO_KEEPALIVE    enables keep connections alive
3125            SO_DONTROUTE    enables routing bypass for outgoing messages
3126            SO_LINGER       linger on close if data present
3127            SO_BROADCAST    enables permission to transmit broadcast messages
3128            SO_OOBINLINE    enables reception of out-of-band data in band
3129            SO_SNDBUF       set buffer size for output
3130            SO_RCVBUF       set buffer size for input
3131            SO_SNDLOWAT     set minimum count for output
3132            SO_RCVLOWAT     set minimum count for input
3133            SO_SNDTIMEO     set timeout value for output
3134            SO_RCVTIMEO     set timeout value for input
3135            SO_TYPE         get the type of the socket (get only)
3136            SO_ERROR        get and clear error on the socket (get only)
3137