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 -->
7 <chapter id="tcpip-library-reference">
8 <title>TCP/IP Library Reference</title>
11 <sect1 id="net-common-tcpip-manpages-getdomainname">
12 <title>getdomainname</title>
14 GETDOMAINNAME(3) BSD Library Functions Manual GETDOMAINNAME(3)
17 getdomainname, setdomainname - get/set YP domain name of current host
20 #include <unistd.h>
23 getdomainname(char *name, size_t namelen);
26 setdomainname(const char *name, size_t namelen);
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-
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.
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-
45 The following errors may be returned by these calls:
47 [EFAULT] The name or namelen parameter gave an invalid address.
49 [EPERM] The caller tried to set the domain name and was not
53 domainname(1), gethostid(3), gethostname(3), sysctl(3), sysctl(8), yp(8)
56 Domain names are limited to MAXHOSTNAMELEN (from <sys/param.h>) charac-
57 ters, currently 256. This includes the terminating NUL character.
59 If the buffer passed to getdomainname() is too small, other operating
60 systems may not guarantee termination with NUL.
63 The getdomainname function call appeared in SunOS 3.x.
69 <sect1 id="net-common-tcpip-manpages-gethostname">
70 <title>gethostname</title>
72 GETHOSTNAME(3) BSD Library Functions Manual GETHOSTNAME(3)
75 gethostname, sethostname - get/set name of current host
78 #include <unistd.h>
81 gethostname(char *name, size_t namelen);
84 sethostname(const char *name, size_t namelen);
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-
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.
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-
103 The following errors may be returned by these calls:
105 [EFAULT] The name or namelen parameter gave an invalid address.
107 [EPERM] The caller tried to set the hostname and was not the
111 hostname(1), getdomainname(3), gethostid(3), sysctl(3), sysctl(8), yp(8)
114 The gethostname() function call conforms to X/Open Portability Guide
115 Issue 4.2 (``XPG4.2'').
118 The gethostname() function call appeared in 4.2BSD.
121 Host names are limited to MAXHOSTNAMELEN (from <sys/param.h>) characters,
122 currently 256. This includes the terminating NUL character.
124 If the buffer passed to gethostname() is smaller than MAXHOSTNAMELEN,
125 other operating systems may not guarantee termination with NUL.
131 <sect1 id="net-common-tcpip-manpages-byteorder">
132 <title>byteorder</title>
134 BYTEORDER(3) BSD Library Functions Manual BYTEORDER(3)
137 htonl, htons, ntohl, ntohs, htobe32, htobe16, betoh32, betoh16, htole32,
138 htole16, letoh32, letoh16, swap32, swap16 - convert values between dif-
139 ferent byte orderings
142 #include <sys/types.h>
143 #include <machine/endian.h>
146 htonl(u_int32_t host32);
149 htons(u_int16_t host16);
152 ntohl(u_int32_t net32);
155 ntohs(u_int16_t net16);
158 htobe32(u_int32_t host32);
161 htobe16(u_int16_t host16);
164 betoh32(u_int32_t big32);
167 betoh16(u_int16_t big16);
170 htole32(u_int32_t host32);
173 htole16(u_int16_t host16);
176 letoh32(u_int32_t little32);
179 letoh16(u_int16_t little16);
182 swap32(u_int32_t val32);
185 swap16(u_int16_t val16);
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.
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:
198 n Network order (big-endian).
199 be Big-endian (most significant byte first).
200 le Little-endian (least significant byte first).
202 One of the specified orderings must be 'h'. {size} will take these
205 l Long (32-bit, used in conjunction with forms involving 'n').
206 s Short (16-bit, used in conjunction with forms involving 'n').
212 The swap functions are of the form: swap{size}.
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.
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
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).
232 gethostbyname(3), getservent(3)
235 The byteorder functions appeared in 4.2BSD.
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
246 <sect1 id="net-common-tcpip-manpages-ethers">
247 <title>ethers</title>
249 ETHERS(3) BSD Library Functions Manual ETHERS(3)
252 ether_aton, ether_ntoa, ether_addr, ether_ntohost, ether_hostton,
253 ether_line - get ethers entry
256 #include <netinet/if_ether.h>
259 ether_ntoa(struct ether_addr *e);
265 ether_ntohost(char *hostname, struct ether_addr *e);
268 ether_hostton(char *hostname, struct ether_addr *e);
271 ether_line(char *l, struct ether_addr *e, char *hostname);
274 Ethernet addresses are represented by the following structure:
277 u_int8_t ether_addr_octet[6];
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.
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.
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.
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.
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
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-
322 BSD December 16, 1993 BSD
326 <sect1 id="net-common-tcpip-manpages-getaddrinfo">
327 <title>getaddrinfo</title>
329 GETADDRINFO(3) BSD Library Functions Manual GETADDRINFO(3)
332 getaddrinfo, freeaddrinfo, gai_strerror - nodename-to-address translation
333 in protocol-independent manner
336 #include <sys/types.h>
337 #include <sys/socket.h>
338 #include <netdb.h>
341 getaddrinfo(const char *nodename, const char *servname,
342 const struct addrinfo *hints, struct addrinfo **res);
345 freeaddrinfo(struct addrinfo *ai);
348 gai_strerror(int ecode);
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-
356 The addrinfo structure is defined as a result of including the <netdb.h>
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 */
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
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.
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.
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
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-
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.
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
430 The arguments to getaddrinfo() must sufficiently be consistent and unam-
431 biguous. Here are pitfall cases you may encounter:
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
493 struct addrinfo hints, *res, *res0;
496 const char *cause = NULL;
498 memset(&hints, 0, sizeof(hints));
499 hints.ai_family = PF_UNSPEC;
500 hints.ai_socktype = SOCK_STREAM;
501 error = getaddrinfo("www.kame.net", "http", &hints, &res0);
503 errx(1, "%s", gai_strerror(error));
507 for (res = res0; res; res = res->ai_next) {
508 s = socket(res->ai_family, res->ai_socktype,
515 if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
522 break; /* okay we got one */
530 The following example tries to open a wildcard listening socket onto ser-
531 vice ``http'', for all the address families available.
533 struct addrinfo hints, *res, *res0;
537 const char *cause = NULL;
539 memset(&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", &hints, &res0);
545 errx(1, "%s", gai_strerror(error));
549 for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
550 s[nsock] = socket(res->ai_family, res->ai_socktype,
552 if (s[nsock] < 0) {
557 if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
562 (void) listen(s[nsock], 5);
573 Error return status from getaddrinfo() is zero on success and non-zero on
574 errors. Non-zero error codes are defined in <netdb.h>, and as follows:
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.
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.
594 getnameinfo(3), gethostbyname(3), getservbyname(3), hosts(5),
595 resolv.conf(5), services(5), hostname(7), named(8)
597 R. Gilligan, S. Thomson, J. Bound, and W. Stevens, Basic Socket Interface
598 Extensions for IPv6, RFC2553, March 1999.
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.
604 Craig Metz, "Protocol Independence Using the Sockets API", Proceedings of
605 the freenix track: 2000 USENIX annual technical conference, June 2000.
608 The implementation first appeared in WIDE Hydrangea IPv6 protocol stack
612 The getaddrinfo() function is defined in IEEE POSIX 1003.1g draft speci-
613 fication, and documented in ``Basic Socket Interface Extensions for
617 The current implementation is not thread-safe.
619 The text was shamelessly copied from RFC2553.
625 <sect1 id="net-common-tcpip-manpages-gethostbyname">
626 <title>gethostbyname</title>
628 GETHOSTBYNAME(3) BSD Library Functions Manual GETHOSTBYNAME(3)
631 gethostbyname, gethostbyname2, gethostbyaddr, gethostent, sethostent,
632 endhostent, hstrerror, herror - get network host entry
635 #include <netdb.h>
639 gethostbyname(const char *name);
642 gethostbyname2(const char *name, int af);
645 gethostbyaddr(const char *addr, int len, int af);
651 sethostent(int stayopen);
657 herror(const char *string);
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.
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 */
678 #define h_addr h_addr_list[0] /* address, for backward compatibility */
680 The members of this structure are:
682 h_name Official name of the host.
684 h_aliases A zero-terminated array of alternate names for the host.
686 h_addrtype The type of address being returned.
688 h_length The length, in bytes, of the address.
690 h_addr_list A zero-terminated array of network addresses for the host.
691 Host addresses are returned in network byte order.
693 h_addr The first address in h_addr_list; this is for backward com-
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).
700 gethostbyname2() is an advanced form of gethostbyname() which allows
701 lookups in address families other than AF_INET, for example AF_INET6.
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.
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.
713 The endhostent() function closes the TCP connection.
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.
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.
731 The variable h_errno can have the following values:
733 HOST_NOT_FOUND No such host is known.
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.
739 NO_RECOVERY Some unexpected server failure was encountered. This is
740 a non-recoverable error.
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.
751 resolver(3), getaddrinfo(3), getnameinfo(3), hosts(5), resolv.conf(5),
752 hostname(7), named(8)
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.
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().
763 The endhostent() function closes the file.
766 The herror() function appeared in 4.3BSD. The endhostent(),
767 gethostbyaddr(), gethostbyname(), gethostent(), and sethostent() func-
768 tions appeared in 4.2BSD.
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.
775 YP does not support any address families other than AF_INET and uses the
776 traditional database format.
778 BSD March 13, 1997 BSD
782 <sect1 id="net-common-tcpip-manpages-getifaddrs">
783 <title>getifaddrs</title>
785 GETIFADDRS(3) BSD Library Functions Manual GETIFADDRS(3)
788 getifaddrs - get interface addresses
791 #include <sys/types.h>
792 #include <sys/socket.h>
793 #include <ifaddrs.h>
796 getifaddrs(struct ifaddrs **ifap);
799 freeifaddrs(struct ifaddrs *ifap);
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 <ifaddrs.h>. The ifaddrs structure contains at least the following
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 */
818 Contains a pointer to the next structure on the list. This field
819 is set to NULL in last structure on the list.
822 Contains the interface name.
825 Contains the interface flags, as set by ifconfig(8).
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.)
834 References the netmask associated with ifa_addr, if one is set,
835 otherwise it is NULL.
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.
843 References the destination address on a P2P interface, if one
844 exists, otherwise it is NULL.
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 <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 <net/if.h>) which contains per-address interface statistics.
854 The data returned by getifaddrs() is dynamically allocated and should be
855 freed using freeifaddrs() when no longer needed.
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.
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).
866 If both <net/if.h> and <ifaddrs.h> are being included, <net/if.h> must be
867 included before <ifaddrs.h>.
870 ioctl(2), socket(2), sysctl(3), networking(4), ifconfig(8)
873 The getifaddrs() function first appeared in BSDI BSD/OS. The function is
874 supplied on OpenBSD since OpenBSD 2.7.
876 BSD October 13, 2005 BSD
880 <sect1 id="net-common-tcpip-manpages-getnameinfo">
881 <title>getnameinfo</title>
883 GETNAMEINFO(3) BSD Library Functions Manual GETNAMEINFO(3)
886 getnameinfo - address-to-nodename translation in protocol-independent
890 #include <sys/types.h>
891 #include <sys/socket.h>
892 #include <netdb.h>
895 getnameinfo(const struct sockaddr *sa, socklen_t salen, char *host,
896 size_t hostlen, char *serv, size_t servlen, int flags);
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.
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-
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.
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-
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 <netdb.h>:
930 #define NI_MAXHOST MAXHOSTNAMELEN
931 #define NI_MAXSERV 32
933 The first value is actually defined as the constant MAXDNAME in recent
934 versions of BIND's <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.
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.
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.
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-
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.
959 These NI_xxx flags are defined in <netdb.h>.
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.
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.
972 struct sockaddr *sa; /* input */
973 char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
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");
980 printf("host=%s, serv=%s\n", hbuf, sbuf);
982 The following version checks if the socket address has reverse address
985 struct sockaddr *sa; /* input */
986 char hbuf[NI_MAXHOST];
988 if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
990 errx(1, "could not resolve hostname");
993 printf("host=%s\n", hbuf);
996 The function indicates successful completion by a zero return value; a
997 non-zero return value indicates failure. Error codes are as below:
999 EAI_AGAIN The name could not be resolved at this time. Future
1000 attempts may succeed.
1002 EAI_BADFLAGS The flags had an invalid value.
1004 EAI_FAIL A non-recoverable error occurred.
1006 EAI_FAMILY The address family was not recognized or the address
1007 length was invalid for the specified family.
1009 EAI_MEMORY There was a memory allocation failure.
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.
1015 EAI_SYSTEM A system error occurred. The error code can be found
1019 getaddrinfo(3), gethostbyaddr(3), getservbyport(3), hosts(5),
1020 resolv.conf(5), services(5), hostname(7), named(8)
1022 R. Gilligan, S. Thomson, J. Bound, and W. Stevens, Basic Socket Interface
1023 Extensions for IPv6, RFC2553, March 1999.
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.
1029 Craig Metz, "Protocol Independence Using the Sockets API", Proceedings of
1030 the freenix track: 2000 USENIX annual technical conference, June 2000.
1033 The implementation first appeared in WIDE Hydrangea IPv6 protocol stack
1037 The getaddrinfo() function is defined IEEE POSIX 1003.1g draft specifica-
1038 tion, and documented in ``Basic Socket Interface Extensions for IPv6''
1042 The current implementation is not thread-safe.
1044 The text was shamelessly copied from RFC2553.
1046 OpenBSD intentionally uses different NI_MAXHOST value from what RFC2553
1047 suggests, to avoid buffer length handling mistakes.
1049 BSD May 25, 1995 BSD
1053 <sect1 id="net-common-tcpip-manpages-getnetent">
1054 <title>getnetent</title>
1056 GETNETENT(3) BSD Library Functions Manual GETNETENT(3)
1059 getnetent, getnetbyaddr, getnetbyname, setnetent, endnetent - get network
1063 #include <netdb.h>
1069 getnetbyname(char *name);
1072 getnetbyaddr(in_addr_t net, int type);
1075 setnetent(int stayopen);
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.
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 */
1092 The members of this structure are:
1094 n_name The official name of the network.
1096 n_aliases A zero-terminated list of alternate names for the network.
1098 n_addrtype The type of the network number returned; currently only
1101 n_net The network number. Network numbers are returned in machine
1104 The getnetent() function reads the next line of the file, opening the
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().
1111 The endnetent() function closes the file.
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.
1123 Null pointer (0) returned on EOF or error.
1126 resolver(3), networks(5)
1129 The getnetent(), getnetbyaddr(), getnetbyname(), setnetent(), and
1130 endnetent() functions appeared in 4.2BSD.
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
1139 BSD March 13, 1997 BSD
1143 <sect1 id="net-common-tcpip-manpages-getprotoent">
1144 <title>getprotoent</title>
1146 GETPROTOENT(3) BSD Library Functions Manual GETPROTOENT(3)
1149 getprotoent, getprotobynumber, getprotobyname, setprotoent, endprotoent -
1153 #include <netdb.h>
1159 getprotobyname(char *name);
1162 getprotobynumber(int proto);
1165 setprotoent(int stayopen);
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,
1178 char *p_name; /* official name of protocol */
1179 char **p_aliases; /* alias list */
1180 int p_proto; /* protocol number */
1183 The members of this structure are:
1185 p_name The official name of the protocol.
1187 p_aliases A zero-terminated list of alternate names for the protocol.
1189 p_proto The protocol number.
1191 The getprotoent() function reads the next line of the file, opening the
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().
1198 The endprotoent() function closes the file.
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.
1205 Null pointer (0) returned on EOF or error.
1214 The getprotoent(), getprotobynumber(), getprotobyname(), setprotoent(),
1215 and endprotoent() functions appeared in 4.2BSD.
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.
1222 BSD June 4, 1993 BSD
1226 <sect1 id="net-common-tcpip-manpages-getrrsetbyname">
1227 <title>getrrsetbyname</title>
1229 GETRRSETBYNAME(3) BSD Library Functions Manual GETRRSETBYNAME(3)
1232 getrrsetbyname - retrieve DNS records
1235 #include <netdb.h>
1238 getrrsetbyname(const char *hostname, unsigned int rdclass,
1239 unsigned int rdtype, unsigned int flags, struct rrsetinfo **res);
1242 freerrset(struct rrsetinfo **rrset);
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.
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.
1260 The following structures are used:
1263 unsigned int rdi_length; /* length of data */
1264 unsigned char *rdi_data; /* record data */
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 */
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().
1286 If the EDNS0 option is activated in resolv.conf(3), getrrsetbyname() will
1287 request DNSSEC authentication using the EDNS0 DNSSEC OK (DO) bit.
1290 getrrsetbyname() returns zero on success, and one of the following error
1291 codes if an error occurred:
1293 ERRSET_NONAME the name does not exist
1294 ERRSET_NODATA the name exists, but does not have data of the desired
1296 ERRSET_NOMEMORY memory could not be allocated
1297 ERRSET_INVAL a parameter is invalid
1298 ERRSET_FAIL other failure
1301 resolver(3), resolv.conf(5), named(8)
1304 Jakob Schlyter <jakob@openbsd.org>
1307 getrrsetbyname() first appeared in OpenBSD 3.0. The API first appeared
1308 in ISC BIND version 9.
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.
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).
1321 BSD Oct 18, 2000 BSD
1325 <sect1 id="net-common-tcpip-manpages-getservent">
1326 <title>getservent</title>
1328 GETSERVENT(3) BSD Library Functions Manual GETSERVENT(3)
1331 getservent, getservbyport, getservbyname, setservent, endservent - get
1335 #include <netdb.h>
1341 getservbyname(char *name, char *proto);
1344 getservbyport(int port, char *proto);
1347 setservent(int stayopen);
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,
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 */
1365 The members of this structure are:
1367 s_name The official name of the service.
1369 s_aliases A zero-terminated list of alternate names for the service.
1371 s_port The port number at which the service resides. Port numbers
1372 are returned in network byte order.
1374 s_proto The name of the protocol to use when contacting the service.
1376 The getservent() function reads the next line of the file, opening the
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().
1383 The endservent() function closes the file.
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.
1395 Null pointer (0) returned on EOF or error.
1398 getprotoent(3), services(5)
1401 The getservent(), getservbyport(), getservbyname(), setservent(), and
1402 endservent() functions appeared in 4.2BSD.
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.
1409 BSD January 12, 1994 BSD
1413 <sect1 id="net-common-tcpip-manpages-if-nametoindex">
1414 <title>if_nametoindex</title>
1416 IF_NAMETOINDEX(3) BSD Library Functions Manual IF_NAMETOINDEX(3)
1419 if_nametoindex, if_indextoname, if_nameindex, if_freenameindex - convert
1420 interface index to name, and vice versa
1423 #include <net/if.h>
1426 if_nametoindex(const char *ifname);
1429 if_indextoname(unsigned int ifindex, char *ifname);
1431 struct if_nameindex *
1435 if_freenameindex(struct if_nameindex *ptr);
1438 These functions map interface indexes to interface names (such as
1439 ``lo0''), and vice versa.
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.
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 <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.
1454 if_nameindex() returns an array of if_nameindex structures.
1455 if_nametoindex is also defined in <net/if.h>, and is as follows:
1457 struct if_nameindex {
1458 unsigned int if_index; /* 1, 2, ... */
1459 char *if_name; /* null terminated name: "le0", ... */
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.
1468 if_freenameindex() takes a pointer that was returned by if_nameindex() as
1469 argument (ptr), and it reclaims the region allocated.
1472 if_nametoindex() returns 0 on error, positive integer on success.
1473 if_indextoname() and if_nameindex() return NULL on errors.
1476 R. Gilligan, S. Thomson, J. Bound, and W. Stevens, ``Basic Socket Inter-
1477 face Extensions for IPv6,'' RFC2553, March 1999.
1480 These functions are defined in ``Basic Socket Interface Extensions for
1483 BSD May 21, 1998 BSD
1487 <sect1 id="net-common-tcpip-manpages-inet">
1490 INET(3) BSD Library Functions Manual INET(3)
1493 inet_addr, inet_aton, inet_lnaof, inet_makeaddr, inet_netof,
1494 inet_network, inet_ntoa, inet_ntop, inet_pton - Internet address manipu-
1498 #include <sys/socket.h>
1499 #include <netinet/in.h>
1500 #include <arpa/inet.h>
1503 inet_addr(const char *cp);
1506 inet_aton(const char *cp, struct in_addr *addr);
1509 inet_lnaof(struct in_addr in);
1512 inet_makeaddr(unsigned long net, unsigned long lna);
1515 inet_netof(struct in_addr in);
1518 inet_network(const char *cp);
1521 inet_ntoa(struct in_addr in);
1524 inet_ntop(int af, const void *src, char *dst, size_t size);
1527 inet_pton(int af, const char *src, void *dst);
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.
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.
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.
1562 INTERNET ADDRESSES (IP VERSION 4)
1563 Values specified using the '.' notation take one of the following forms:
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
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''.
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''.
1588 When only one part is given, the value is stored directly in the network
1589 address without any byte rearrangement.
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).
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.
1600 The presentation format of an IPv6 address is given in [RFC1884 2.2]:
1602 There are three conventional forms for representing IPv6 addresses as
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-
1609 FEDC:BA98:7654:3210:FEDC:BA98:7654:3210
1610 1080:0:0:0:8:800:200C:417A
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.).
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
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.
1626 For example the following addresses:
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
1633 may be represented as:
1635 1080::8:800:200C:417A a unicast address
1636 FF01::43 a multicast address
1637 ::1 the loopback address
1638 :: the unspecified addresses
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:
1647 0:0:0:0:0:0:13.1.68.3
1648 0:0:0:0:0:FFFF:129.144.52.38
1650 or in compressed form:
1653 ::FFFF:129.144.52.38
1656 The constant INADDR_NONE is returned by inet_addr() and inet_network()
1657 for malformed requests.
1660 byteorder(3), gethostbyname(3), getnetent(3), inet_net(3), hosts(5),
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.
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
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.
1682 The problem of host byte ordering versus network byte ordering is confus-
1685 The string returned by inet_ntoa() resides in a static memory area.
1687 BSD June 18, 1997 BSD
1691 <sect1 id="net-common-tcpip-manpages-inet6-option-space">
1692 <title>inet6_option_space</title>
1694 INET6_OPTION_SPACE(3) BSD Library Functions Manual INET6_OPTION_SPACE(3)
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
1702 #include <netinet/in.h>
1705 inet6_option_space(int nbytes);
1708 inet6_option_init(void *bp, struct cmsghdr **cmsgp, int type);
1711 inet6_option_append(struct cmsghdr *cmsg, const u_int8_t *typep,
1712 int multx, int plusy);
1715 inet6_option_alloc(struct cmsghdr *cmsg, int datalen, int multx,
1719 inet6_option_next(const struct cmsghdr *cmsg, u_int8_t **tptrp);
1722 inet6_option_find(const struct cmsghdr *cmsg, u_int8_t **tptrp,
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 <netinet/in.h>
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
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
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.
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().
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.
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.
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.
1771 cmsg is a pointer to the cmsghdr structure that must have been initial-
1772 ized by inet6_option_init().
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-
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.)
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.
1786 multx is the value x in the alignment term ``xn + y''. It must have a
1787 value of 1, 2, 4, or 8.
1789 plusy is the value y in the alignment term ``xn + y''. It must have a
1790 value between 0 and 7, inclusive.
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.
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
1804 cmsg is a pointer to the cmsghdr structure that must have been initial-
1805 ized by inet6_option_init().
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.)
1813 multx is the value x in the alignment term ``xn + y''. It must have a
1814 value of 1, 2, 4, or 8.
1816 plusy is the value y in the alignment term ``xn + y''. It must have a
1817 value between 0 and 7, inclusive.
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.
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.
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.
1836 Each time this function returns success, *tptrp points to the 8-bit
1837 option type field for the next option to be processed.
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
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.
1859 inet6_option_init() and inet6_option_append() return 0 on success or -1
1862 inet6_option_alloc() returns NULL on an error.
1864 On errors, inet6_option_next() and inet6_option_find() return -1 setting
1865 *tptrp to non NULL value.
1868 RFC2292 gives comprehensive examples in chapter 6.
1871 W. Stevens and M. Thomas, Advanced Sockets API for IPv6, RFC2292,
1874 S. Deering and R. Hinden, Internet Protocol, Version 6 (IPv6)
1875 Specification, RFC2460, December 1998.
1878 The implementation first appeared in KAME advanced networking kit.
1881 The functions are documented in ``Advanced Sockets API for IPv6''
1885 The text was shamelessly copied from RFC2292.
1887 BSD December 10, 1999 BSD
1891 <sect1 id="net-common-tcpip-manpages-inet6-rthdr-space">
1892 <title>inet6_rthdr_space</title>
1894 INET6_RTHDR_SPACE(3) BSD Library Functions Manual INET6_RTHDR_SPACE(3)
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
1903 #include <netinet/in.h>
1906 inet6_rthdr_space(int type, int segments);
1909 inet6_rthdr_init(void *bp, int type);
1912 inet6_rthdr_add(struct cmsghdr *cmsg, const struct in6_addr *addr,
1913 unsigned int flags);
1916 inet6_rthdr_lasthop(struct cmsghdr *cmsg, unsigned int flags);
1919 inet6_rthdr_reverse(const struct cmsghdr *in, struct cmsghdr *out);
1922 inet6_rthdr_segments(const struct cmsghdr *cmsg);
1925 inet6_rthdr_getaddr(struct cmsghdr *cmsg, int index);
1928 inet6_rthdr_getflags(const struct cmsghdr *cmsg, int index);
1931 RFC2292 IPv6 advanced API defines eight functions that the application
1932 calls to build and examine a Routing header. Four functions build a
1935 inet6_rthdr_space() return #bytes required for ancillary data
1937 inet6_rthdr_init() initialize ancillary data for Routing header
1939 inet6_rthdr_add() add IPv6 address & flags to Routing header
1941 inet6_rthdr_lasthop() specify the flags for the final hop
1943 Four functions deal with a returned Routing header:
1945 inet6_rthdr_reverse() reverse a Routing header
1947 inet6_rthdr_segments() return #segments in a Routing header
1949 inet6_rthdr_getaddr() fetch one address from a Routing header
1951 inet6_rthdr_getflags() fetch one flag from a Routing header
1953 The function prototypes for these functions are all in the <netinet/in.h>
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
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.
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
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.
1981 The caller must allocate the buffer and its size can be determined by
1982 calling inet6_rthdr_space().
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.
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.
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.
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.
2003 The return value of the function is 0 upon success, or -1 upon an error.
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().
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
2016 The return value of the function is 0 on success, or -1 upon an error.
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
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.
2031 Upon an error the return value of the function is NULL.
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.
2039 Upon an error the return value of the function is -1.
2041 Note: Addresses are indexed starting at 1, and flags starting at 0, to
2042 maintain consistency with the terminology and figures in RFC2460.
2045 inet6_rthdr_space() returns 0 on errors.
2047 inet6_rthdr_add(), inet6_rthdr_lasthop() and inet6_rthdr_reverse() return
2048 0 on success, and returns -1 on error.
2050 inet6_rthdr_init() and inet6_rthdr_getaddr() return NULL on error.
2052 inet6_rthdr_segments() and inet6_rthdr_getflags() return -1 on error.
2055 RFC2292 gives comprehensive examples in chapter 8.
2058 W. Stevens and M. Thomas, Advanced Sockets API for IPv6, RFC2292,
2061 S. Deering and R. Hinden, Internet Protocol, Version 6 (IPv6)
2062 Specification, RFC2460, December 1998.
2065 The implementation first appeared in KAME advanced networking kit.
2068 The functions are documented in ``Advanced Sockets API for IPv6''
2072 The text was shamelessly copied from RFC2292.
2074 inet6_rthdr_reverse() is not implemented yet.
2076 BSD December 10, 1999 BSD
2080 <sect1 id="net-common-tcpip-manpages-inet-net">
2081 <title>inet_net</title>
2083 INET_NET(3) BSD Library Functions Manual INET_NET(3)
2086 inet_net_ntop, inet_net_pton - Internet network number manipulation rou-
2090 #include <sys/socket.h>
2091 #include <netinet/in.h>
2092 #include <arpa/inet.h>
2095 inet_net_ntop(int af, const void *src, int bits, char *dst, size_t size);
2098 inet_net_pton(int af, const char *src, void *dst, size_t size);
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
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).
2117 The only value for af currently supported is AF_INET. size is the size
2118 of the result buffer dst.
2120 NETWORK NUMBERS (IP VERSION 4)
2121 Internet network numbers may be specified in one of the following forms:
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
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''.
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''.
2147 When only one part is given, the value is stored directly in the Internet
2148 network number without any byte rearrangement.
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).
2156 byteorder(3), inet(3), networks(5)
2159 The inet_net_ntop and inet_net_pton functions first appeared in BIND
2162 BSD June 18, 1997 BSD
2166 <sect1 id="net-common-tcpip-manpages-ipx">
2169 IPX(3) BSD Library Functions Manual IPX(3)
2172 ipx_addr, ipx_ntoa - IPX address conversion routines
2175 #include <sys/types.h>
2176 #include <netipx/ipx.h>
2179 ipx_addr(const char *cp);
2182 ipx_ntoa(struct ipx_addr ipx);
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:
2190 <network number>.<host number>.<port number>
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.
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.
2215 ns(4), hosts(5), networks(5)
2218 The precursor ns_addr() and ns_ntoa() functions appeared in 4.3BSD.
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.
2225 BSD June 4, 1993 BSD
2229 <sect1 id="net-common-tcpip-manpages-iso-addr">
2230 <title>iso_addr</title>
2232 ISO_ADDR(3) BSD Library Functions Manual ISO_ADDR(3)
2235 iso_addr, iso_ntoa - network address conversion routines for Open System
2239 #include <sys/types.h>
2240 #include <netiso/iso.h>
2246 iso_ntoa(struct iso_addr *isoa);
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().
2255 Unfortunately, no universal standard exists for representing OSI network
2258 The format employed by iso_addr() is a sequence of hexadecimal ``digits''
2259 (optionally separated by periods), of the form:
2261 <hex digits>.<hex digits>.<hex digits>
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.
2270 iso_ntoa() always returns a null terminated string. iso_addr() always
2271 returns a pointer to a struct iso_addr. (See BUGS.)
2277 The iso_addr() and iso_ntoa() functions appeared in 4.3BSD-Reno.
2280 The returned values reside in a static memory area.
2282 The function iso_addr() should diagnose improperly formed input, and
2283 there should be an unambiguous way to recognize this.
2285 BSD June 4, 1993 BSD
2289 <sect1 id="net-common-tcpip-manpages-link-addr">
2290 <title>link_addr</title>
2292 LINK_ADDR(3) BSD Library Functions Manual LINK_ADDR(3)
2295 link_addr, link_ntoa - elementary address specification routines for link
2299 #include <sys/types.h>
2300 #include <sys/socket.h>
2301 #include <net/if_dl.h>
2304 link_addr(const char *addr, struct sockaddr_dl *sdl);
2307 link_ntoa(const struct sockaddr_dl *sdl);
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.
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.
2324 Thus le0:8.0.9.13.d.30 represents an Ethernet address to be transmitted
2325 on the first Lance Ethernet interface.
2328 link_ntoa() always returns a null-terminated string. link_addr() has no
2329 return value. (See BUGS.)
2335 The link_addr() and link_ntoa() functions appeared in 4.3BSD-Reno.
2338 The returned values for link_ntoa reside in a static memory area.
2340 The function link_addr() should diagnose improperly formed input, and
2341 there should be an unambiguous way to recognize this.
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.
2348 BSD July 28, 1993 BSD
2352 <sect1 id="net-common-tcpip-manpages-net-addrcmp">
2353 <title>net_addrcmp</title>
2355 NET_ADDRCMP(3) BSD Library Functions Manual NET_ADDRCMP(3)
2358 net_addrcmp - compare socket address structures
2361 #include <netdb.h>
2364 net_addrcmp(struct sockaddr *sa1, struct sockaddr *sa2);
2367 The net_addrcmp() function compares two socket address structures, sa1
2371 If sa1 and sa2 are for the same address, net_addrcmp() returns 0.
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.
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.
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 <0 is returned.
2387 A net_addrcmp() function was added in OpenBSD 2.5.
2389 BSD July 3, 1999 BSD
2393 <sect1 id="net-common-tcpip-manpages-ns">
2396 NS(3) BSD Library Functions Manual NS(3)
2399 ns_addr, ns_ntoa - Xerox NS(tm) address conversion routines
2402 #include <sys/types.h>
2403 #include <netns/ns.h>
2409 ns_ntoa(struct ns_addr ns);
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-
2418 <network number>.<host number>.<port number>
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.
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.
2445 hosts(5), networks(5)
2448 The ns_addr() and ns_toa() functions appeared in 4.3BSD.
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.
2455 BSD June 4, 1993 BSD
2459 <sect1 id="net-common-tcpip-manpages-resolver">
2460 <title>resolver</title>
2462 RESOLVER(3) BSD Library Functions Manual RESOLVER(3)
2465 res_query, res_search, res_mkquery, res_send, res_init, dn_comp,
2466 dn_expand - resolver routines
2469 #include <sys/types.h>
2470 #include <netinet/in.h>
2471 #include <arpa/nameser.h>
2472 #include <resolv.h>
2475 res_query(char *dname, int class, int type, u_char *answer, int anslen);
2478 res_search(char *dname, int class, int type, u_char *answer, int anslen);
2481 res_mkquery(int op, char *dname, int class, int type, char *data,
2482 int datalen, struct rrec *newrr, char *buf, int buflen);
2485 res_send(char *msg, int msglen, char *answer, int anslen);
2491 dn_comp(char *exp_dn, char *comp_dn, int length, char **dnptrs,
2495 dn_expand(u_char *msg, u_char *eomorig, u_char *comp_dn, u_char *exp_dn,
2499 These routines are used for making, sending, and interpreting query and
2500 reply messages with Internet domain name servers.
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 <resolv.h> and are as follows. Options are stored as a simple
2506 bit mask containing the bitwise OR of the options enabled.
2508 RES_INIT True if the initial name server address and default domain
2509 name are initialized (i.e., res_init() has been called).
2511 RES_DEBUG Print debugging messages.
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-
2518 RES_USEVC Use TCP connections for queries instead of UDP datagrams.
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
2525 RES_IGNTC Unused currently (ignore truncation errors, i.e., don't
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.)
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.
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
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.
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
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.
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.
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 <arpa/nameser.h>. The domain name for the query
2580 is given by dname. newrr is currently unused but is intended for making
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.
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.
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
2607 /etc/resolv.conf configuration file see resolv.conf(5).
2610 gethostbyname(3), resolv.conf(5), hostname(7), named(8)
2612 RFC1032, RFC1033, RFC1034, RFC1035, RFC1535, RFC974
2614 Name Server Operations Guide for BIND.
2617 The res_query function appeared in 4.3BSD.
2619 BSD June 4, 1993 BSD
2623 <sect1 id="net-common-tcpip-manpages-accept">
2624 <title>accept</title>
2626 ACCEPT(2) BSD System Calls Manual ACCEPT(2)
2629 accept - accept a connection on a socket
2632 #include <sys/types.h>
2633 #include <sys/socket.h>
2636 accept(int s, struct sockaddr *addr, socklen_t *addrlen);
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.
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.
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.
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.
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-
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.
2681 The accept() will fail if:
2683 [EBADF] The descriptor is invalid.
2685 [ENOTSOCK] The descriptor references a file, not a socket.
2687 [EOPNOTSUPP] The referenced socket is not of type SOCK_STREAM.
2689 [EINVAL] The referenced socket is not listening for connections
2690 (that is, listen(2) has not yet been called).
2692 [EFAULT] The addr parameter is not in a writable part of the
2695 [EWOULDBLOCK] The socket is marked non-blocking and no connections
2696 are present to be accepted.
2698 [EMFILE] The per-process descriptor table is full.
2700 [ENFILE] The system file table is full.
2702 [ECONNABORTED] A connection has been aborted.
2705 bind(2), connect(2), listen(2), poll(2), select(2), poll(2), socket(2)
2708 The accept() function appeared in 4.2BSD.
2710 BSD February 15, 1999 BSD
2714 <sect1 id="net-common-tcpip-manpages-bind">
2717 BIND(2) BSD System Calls Manual BIND(2)
2720 bind - bind a name to a socket
2723 #include <sys/types.h>
2724 #include <sys/socket.h>
2727 bind(int s, const struct sockaddr *name, socklen_t namelen);
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.
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
2739 The rules used in name binding vary between communication domains. Con-
2740 sult the manual entries in section 4 for detailed information.
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.
2747 The bind() call will fail if:
2749 [EBADF] S is not a valid descriptor.
2751 [ENOTSOCK] S is not a socket.
2753 [EADDRNOTAVAIL] The specified address is not available from the local
2756 [EADDRINUSE] The specified address is already in use.
2758 [EINVAL] The socket is already bound to an address.
2760 [EINVAL] The family of the socket and that requested in
2761 name->sa_family are not equivalent.
2763 [EACCES] The requested address is protected, and the current
2764 user has inadequate permission to access it.
2766 [EFAULT] The name parameter is not in a valid part of the user
2769 The following errors are specific to binding names in the UNIX domain.
2771 [ENOTDIR] A component of the path prefix is not a directory.
2773 [ENAMETOOLONG] A component of a pathname exceeded {NAME_MAX} charac-
2774 ters, or an entire path name exceeded {PATH_MAX} char-
2777 [ENOENT] A prefix component of the path name does not exist.
2779 [ELOOP] Too many symbolic links were encountered in translat-
2782 [EIO] An I/O error occurred while making the directory entry
2783 or allocating the inode.
2785 [EROFS] The name would reside on a read-only file system.
2787 [EISDIR] An empty pathname was specified.
2790 connect(2), getsockname(2), listen(2), socket(2)
2793 The bind() function call appeared in 4.2BSD.
2795 BSD February 15, 1999 BSD
2799 <sect1 id="net-common-tcpip-manpages-connect">
2800 <title>connect</title>
2802 CONNECT(2) BSD System Calls Manual CONNECT(2)
2805 connect - initiate a connection on a socket
2808 #include <sys/types.h>
2809 #include <sys/socket.h>
2812 connect(int s, const struct sockaddr *name, socklen_t namelen);
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.
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.
2832 The connect() call fails if:
2834 [EBADF] S is not a valid descriptor.
2836 [ENOTSOCK] S is a descriptor for a file, not a socket.
2838 [EADDRNOTAVAIL] The specified address is not available on this
2841 [EAFNOSUPPORT] Addresses in the specified address family cannot be
2842 used with this socket.
2844 [EISCONN] The socket is already connected.
2846 [ETIMEDOUT] Connection establishment timed out without establish-
2849 [EINVAL] A TCP connection with a local broadcast, the all-ones
2850 or a multicast address as the peer was attempted.
2852 [ECONNREFUSED] The attempt to connect was forcefully rejected.
2854 [EINTR] A connect was interrupted before it succeeded by the
2855 delivery of a signal.
2857 [ENETUNREACH] The network isn't reachable from this host.
2859 [EADDRINUSE] The address is already in use.
2861 [EFAULT] The name parameter specifies an area outside the pro-
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.
2870 [EALREADY] The socket is non-blocking and a previous connection
2871 attempt has not yet been completed.
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.
2876 [ENOTDIR] A component of the path prefix is not a directory.
2878 [ENAMETOOLONG] A component of a pathname exceeded {NAME_MAX} charac-
2879 ters, or an entire path name exceeded {PATH_MAX} char-
2882 [ENOENT] The named socket does not exist.
2884 [EACCES] Search permission is denied for a component of the
2887 [EACCES] Write access to the named socket is denied.
2889 [ELOOP] Too many symbolic links were encountered in translat-
2893 accept(2), getsockname(2), getsockopt(2), poll(2), select(2), socket(2)
2896 The connect() function call appeared in 4.2BSD.
2898 BSD February 15, 1999 BSD
2902 <sect1 id="net-common-tcpip-manpages-getpeername">
2903 <title>getpeername</title>
2905 GETPEERNAME(2) BSD System Calls Manual GETPEERNAME(2)
2908 getpeername - get name of connected peer
2911 #include <sys/types.h>
2912 #include <sys/socket.h>
2915 getpeername(int s, struct sockaddr *name, socklen_t *namelen);
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.
2923 getpeername() takes three parameters:
2925 s Contains the file descriptor of the socket whose peer should be looked
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 *).
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.
2939 namelen Indicates the amount of space pointed to by name, in bytes.
2941 If address information for the local end of the socket is required, the
2942 getsockname(2) function should be used instead.
2944 If name does not point to enough space to hold the entire socket address,
2945 the result will be truncated to namelen bytes.
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.
2953 On failure, errno is set to one of the following:
2955 [EBADF] The argument s is not a valid descriptor.
2957 [ENOTSOCK] The argument s is a file, not a socket.
2959 [ENOTCONN] The socket is not connected.
2961 [ENOBUFS] Insufficient resources were available in the system to
2962 perform the operation.
2964 [EFAULT] The name parameter points to memory not in a valid
2965 part of the process address space.
2968 accept(2), bind(2), getsockname(2), getpeereid(2), socket(2)
2971 The getpeername() function call appeared in 4.2BSD.
2973 BSD July 17, 1999 BSD
2977 <sect1 id="net-common-tcpip-manpages-getsockname">
2978 <title>getsockname</title>
2980 GETSOCKNAME(2) BSD System Calls Manual GETSOCKNAME(2)
2983 getsockname - get socket name
2986 #include <sys/types.h>
2987 #include <sys/socket.h>
2990 getsockname(int s, struct sockaddr *name, socklen_t *namelen);
2993 getsockname() returns the locally bound address information for a speci-
2996 Common uses of this function are as follows:
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.
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.
3005 o When a function wishes to know the address family of a socket,
3006 getsockname() can be used.
3008 getsockname() takes three parameters:
3010 s, Contains the file desriptor for the socket to be looked up.
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 *).
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.
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-
3026 If the address of the destination socket for a given socket connection is
3027 needed, the getpeername(2) function should be used instead.
3029 If name does not point to enough space to hold the entire socket address,
3030 the result will be truncated to namelen bytes.
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.
3038 If getsockname() fails, errno is set to one of the following:
3040 [EBADF] The argument s is not a valid descriptor.
3042 [ENOTSOCK] The argument s is a file, not a socket.
3044 [ENOBUFS] Insufficient resources were available in the system to
3045 perform the operation.
3047 [EFAULT] The name parameter points to memory not in a valid
3048 part of the process address space.
3051 accept(2), bind(2), getpeername(2), getpeereid(2), socket(2)
3054 Names bound to sockets in the UNIX domain are inaccessible; getsockname
3055 returns a zero length name.
3058 The getsockname() function call appeared in 4.2BSD.
3060 BSD July 17, 1999 BSD
3064 <sect1 id="net-common-tcpip-manpages-getsockopt">
3065 <title>getsockopt</title>
3067 GETSOCKOPT(2) BSD System Calls Manual GETSOCKOPT(2)
3070 getsockopt, setsockopt - get and set options on sockets
3073 #include <sys/types.h>
3074 #include <sys/socket.h>
3077 getsockopt(int s, int level, int optname, void *optval,
3081 setsockopt(int s, int level, int optname, const void *optval,
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.
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).
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,
3105 optname and any specified options are passed uninterpreted to the appro-
3106 priate protocol module for interpretation. The include file
3107 <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.
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 <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 <sys/time.h>.
3118 The following options are recognized at the socket level. Except as
3119 noted, each may be examined with getsockopt() and set with setsockopt().
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)
3138 SO_DEBUG enables debugging in the underlying protocol modules.
3139 SO_REUSEADDR indicates that the rules used in validating addresses sup-
3140 plied in a bind(2) call should allow reuse of local addresses.
3141 SO_REUSEPORT allows completely duplicate bindings by multiple processes
3142 if they all set SO_REUSEPORT before binding the port. This option per-
3143 mits multiple instances of a program to each receive UDP/IP multicast or
3144 broadcast datagrams destined for the bound port. SO_KEEPALIVE enables
3145 the periodic transmission of messages on a connected socket. Should the
3146 connected party fail to respond to these messages, the connection is con-
3147 sidered broken and processes using the socket are notified via a SIGPIPE
3148 signal when attempting to send data. SO_DONTROUTE indicates that outgo-
3149 ing messages should bypass the standard routing facilities. Instead,
3150 messages are directed to the appropriate network interface according to
3151 the network portion of the destination address.
3153 SO_LINGER controls the action taken when unsent messages are queued on
3154 socket and a close(2) is performed. If the socket promises reliable
3155 delivery of data and SO_LINGER is set, the system will block the process
3156 on the close(2) attempt until it is able to transmit the data or until it
3157 decides it is unable to deliver the information (a timeout period mea-
3158 sured in seconds, termed the linger interval, is specified in the
3159 setsockopt() call when SO_LINGER is requested). If SO_LINGER is disabled
3160 and a close(2) is issued, the system will process the close in a manner
3161 that allows the process to continue as quickly as possible.
3163 The option SO_BROADCAST requests permission to send broadcast datagrams
3164 on the socket. Broadcast was a privileged operation in earlier versions
3165 of the system. With protocols that support out-of-band data, the
3166 SO_OOBINLINE option requests that out-of-band data be placed in the nor-
3167 mal data input queue as received; it will then be accessible with recv(2)
3168 or read(2) calls without the MSG_OOB flag. Some protocols always behave
3169 as if this option is set. SO_SNDBUF and SO_RCVBUF are options to adjust
3170 the normal buffer sizes allocated for output and input buffers, respec-
3171 tively. The buffer size may be increased for high-volume connections, or
3172 may be decreased to limit the possible backlog of incoming data. The
3173 system places an absolute limit on these values.
3175 SO_SNDLOWAT is an option to set the minimum count for output operations.
3176 Most output operations process all of the data supplied by the call,
3177 delivering data to the protocol for transmission and blocking as neces-
3178 sary for flow control. Nonblocking output operations will process as
3179 much data as permitted subject to flow control without blocking, but will
3180 process no data if flow control does not allow the smaller of the low
3181 water mark value or the entire request to be processed. A select(2) or
3182 poll(2) operation testing the ability to write to a socket will return
3183 true only if the low water mark amount could be processed. The default
3184 value for SO_SNDLOWAT is set to a convenient size for network efficiency,
3185 often 1024. SO_RCVLOWAT is an option to set the minimum count for input
3186 operations. In general, receive calls will block until any (non-zero)
3187 amount of data is received, then return with the smaller of the amount
3188 available or the amount requested. The default value for SO_RCVLOWAT is
3189 1. If SO_RCVLOWAT is set to a larger value, blocking receive calls nor-
3190 mally wait until they have received the smaller of the low water mark
3191 value or the requested amount. Receive calls may still return less than
3192 the low water mark if an error occurs, a signal is caught, or the type of
3193 data next in the receive queue is different than that returned.
3195 SO_SNDTIMEO is an option to set a timeout value for output operations.
3196 It accepts a struct timeval parameter with the number of seconds and
3197 microseconds used to limit waits for output operations to complete. If a
3198 send operation has blocked for this much time, it returns with a partial
3199 count or with the error EWOULDBLOCK if no data was sent. In the current
3200 implementation, this timer is restarted each time additional data are
3201 delivered to the protocol, implying that the limit applies to output por-
3202 tions ranging in size from the low water mark to the high water mark for
3203 output. SO_RCVTIMEO is an option to set a timeout value for input opera-
3204 tions. It accepts a struct timeval parameter with the number of seconds
3205 and microseconds used to limit waits for input operations to complete.
3206 In the current implementation, this timer is restarted each time addi-
3207 tional data are received by the protocol, and thus the limit is in effect
3208 an inactivity timer. If a receive operation has been blocked for this
3209 much time without receiving additional data, it returns with a short
3210 count or with the error EWOULDBLOCK if no data were received.
3212 Finally, SO_TYPE and SO_ERROR are options used only with getsockopt().
3213 SO_TYPE returns the type of the socket, such as SOCK_STREAM; it is useful
3214 for servers that inherit sockets on startup. SO_ERROR returns any pend-
3215 ing error on the socket and clears the error status. It may be used to
3216 check for asynchronous errors on connected datagram sockets or for other
3217 asynchronous errors.
3220 A 0 is returned if the call succeeds, -1 if it fails.
3223 The call succeeds unless:
3225 [EBADF] The argument s is not a valid descriptor.
3227 [ENOTSOCK] The argument s is a file, not a socket.
3229 [ENOPROTOOPT] The option is unknown at the level indicated.
3231 [EFAULT] The address pointed to by optval is not in a valid
3232 part of the process address space. For getsockopt(),
3233 this error may also be returned if optlen is not in a
3234 valid part of the process address space.
3237 connect(2), ioctl(2), poll(2), select(2), poll(2), socket(2),
3238 getprotoent(3), protocols(5)
3241 Several of the socket options should be handled at lower levels of the
3245 The getsockopt() system call appeared in 4.2BSD.
3247 BSD February 15, 1999 BSD
3251 <sect1 id="net-common-tcpip-manpages-ioctl">
3252 <title>ioctl</title>
3254 IOCTL(2) BSD System Calls Manual IOCTL(2)
3257 ioctl - control device
3260 #include <sys/ioctl.h>
3263 ioctl(int d, unsigned long request, ...);
3266 The ioctl() function manipulates the underlying device parameters of spe-
3267 cial files. In particular, many operating characteristics of character
3268 special files (e.g., terminals) may be controlled with ioctl() requests.
3270 The argument d must be an open file descriptor. The third argument is
3271 called arg and contains additional information needed by this device to
3272 perform the requested function. arg is either an int or a pointer to a
3273 device-specific data structure, depending upon the given request.
3275 An ioctl request has encoded in it whether the argument is an ``in''
3276 parameter or ``out'' parameter, and the size of the third argument (arg)
3277 in bytes. Macros and defines used in specifying an ioctl request are
3278 located in the file <sys/ioctl.h>.
3281 If an error has occurred, a value of -1 is returned and errno is set to
3285 ioctl() will fail if:
3287 [EBADF] d is not a valid descriptor.
3289 [ENOTTY] d is not associated with a character special device.
3291 [ENOTTY] The specified request does not apply to the kind of
3292 object that the descriptor d references.
3294 [EINVAL] request or arg is not valid.
3296 [EFAULT] arg points outside the process's allocated address
3300 cdio(1), chio(1), mt(1), execve(2), fcntl(2), intro(4), tty(4)
3303 An ioctl() function call appeared in Version 7 AT&T UNIX.
3305 BSD December 11, 1993 BSD
3309 <sect1 id="net-common-tcpip-manpages-poll">
3312 POLL(2) BSD System Calls Manual POLL(2)
3315 poll - synchronous I/O multiplexing
3318 #include <poll.h>
3321 poll(struct pollfd *fds, int nfds, int timeout);
3324 poll() provides a mechanism for reporting I/O conditions across a set of
3327 The arguments are as follows:
3329 fds Points to an array of pollfd structures, which are defined as:
3337 The fd member is an open file descriptor. The events and
3338 revents members are bitmasks of conditions to monitor and condi-
3339 tions found, respectively.
3341 nfds The number of pollfd structures in the array.
3343 timeout Maximum interval to wait for the poll to complete, in millisec-
3344 onds. If this value is 0, then poll() will return immediately.
3345 If this value is INFTIM (-1), poll() will block indefinitely
3346 until a condition is found.
3348 The calling process sets the events bitmask and poll() sets the revents
3349 bitmask. Each call to poll() resets the revents bitmask for accuracy.
3350 The condition flags in the bitmasks are defined as:
3352 POLLIN Data is available on the file descriptor for reading.
3354 POLLNORM Same as POLLIN.
3356 POLLPRI Same as POLLIN.
3358 POLLOUT Data can be written to the file descriptor without blocking.
3360 POLLERR This flag is not used in this implementation and is provided
3361 only for source code compatibility.
3363 POLLHUP The file descriptor was valid before the polling process and
3364 invalid after. Presumably, this means that the file descrip-
3365 tor was closed sometime during the poll.
3367 POLLNVAL The corresponding file descriptor is invalid.
3369 POLLRDNORM Same as POLLIN.
3371 POLLRDBAND Same as POLLIN.
3373 POLLWRNORM Same as POLLOUT.
3375 POLLWRBAND Same as POLLOUT.
3377 POLLMSG This flag is not used in this implementation and is provided
3378 only for source code compatibility.
3380 All flags except POLLIN, POLLOUT, and their synonyms are for use only in
3381 the revents member of the pollfd structure. An attempt to set any of
3382 these flags in the events member will generate an error condition.
3384 In addition to I/O multiplexing, poll() can be used to generate simple
3385 timeouts. This functionality may be achieved by passing a null pointer
3389 The POLLHUP flag is only a close approximation and may not always be
3393 Upon error, poll() returns a -1 and sets the global variable errno to
3394 indicate the error. If the timeout interval was reached before any
3395 events occurred, a 0 is returned. Otherwise, poll() returns the number
3396 of file descriptors for which revents is non-zero.
3399 poll() will fail if:
3401 [EINVAL] nfds was either a negative number or greater than the number
3402 of available file descriptors.
3404 [EINVAL] An invalid flags was set in the events member of the pollfd
3407 [EINVAL] The timeout passed to poll() was too large.
3409 [EAGAIN] Resource allocation failed inside of poll(). Subsequent calls
3410 to poll() may succeed.
3412 [EINTR] poll() caught a signal during the polling process.
3415 poll(2), select(2), sysconf(3)
3418 A poll() system call appeared in AT&T System V UNIX.
3420 BSD December 13, 1994 BSD
3424 <sect1 id="net-common-tcpip-manpages-select">
3425 <title>select</title>
3427 SELECT(2) BSD System Calls Manual SELECT(2)
3430 select - synchronous I/O multiplexing
3433 #include <sys/types.h>
3434 #include <sys/time.h>
3435 #include <unistd.h>
3438 select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds,
3439 struct timeval *timeout);
3441 FD_SET(fd, &fdset);
3443 FD_CLR(fd, &fdset);
3445 FD_ISSET(fd, &fdset);
3447 FD_ZERO(&fdset);
3450 select() examines the I/O descriptor sets whose addresses are passed in
3451 readfds, writefds, and exceptfds to see if some of their descriptors are
3452 ready for reading, are ready for writing, or have an exceptional condi-
3453 tion pending, respectively. The first nfds descriptors are checked in
3454 each set; i.e., the descriptors from 0 through nfds-1 in the descriptor
3455 sets are examined. On return, select() replaces the given descriptor
3456 sets with subsets consisting of those descriptors that are ready for the
3457 requested operation. select() returns the total number of ready descrip-
3458 tors in all the sets.
3460 The descriptor sets are stored as bit fields in arrays of integers. The
3461 following macros are provided for manipulating such descriptor sets:
3462 FD_ZERO(&fdset) initializes a descriptor set fdset to the null set.
3463 FD_SET(fd, &fdset) includes a particular descriptor fd in fdset.
3464 FD_CLR(fd, &fdset) removes fd from fdset. FD_ISSET(fd, &fdset) is non-
3465 zero if fd is a member of fdset, zero otherwise. The behavior of these
3466 macros is undefined if a descriptor value is less than zero or greater
3467 than or equal to FD_SETSIZE, which is normally at least equal to the max-
3468 imum number of descriptors supported by the system.
3470 If timeout is a non-null pointer, it specifies a maximum interval to wait
3471 for the selection to complete. If timeout is a null pointer, the select
3472 blocks indefinitely. To effect a poll, the timeout argument should be
3473 non-null, pointing to a zero-valued timeval structure. timeout is not
3474 changed by select(), and may be reused on subsequent calls; however, it
3475 is good style to re-initialize it before each invocation of select().
3477 Any of readfds, writefds, and exceptfds may be given as null pointers if
3478 no descriptors are of interest.
3481 select() returns the number of ready descriptors that are contained in
3482 the descriptor sets, or -1 is an error occurred. If the time limit
3483 expires, select() returns 0. If select() returns with an error, includ-
3484 ing one due to an interrupted call, the descriptor sets will be unmodi-
3488 An error return from select() indicates:
3490 [EFAULT] One or more of readfds, writefds, or exceptfds points
3491 outside the process's allocated address space.
3493 [EBADF] One of the descriptor sets specified an invalid
3496 [EINTR] A signal was delivered before the time limit expired
3497 and before any of the selected events occurred.
3499 [EINVAL] The specified time limit is invalid. One of its com-
3500 ponents is negative or too large.
3503 accept(2), connect(2), gettimeofday(2), poll(2), read(2), recv(2),
3504 send(2), write(2), getdtablesize(3)
3507 Although the provision of getdtablesize(3) was intended to allow user
3508 programs to be written independent of the kernel limit on the number of
3509 open files, the dimension of a sufficiently large bit field for select
3510 remains a problem. The default bit size of fd_set is based on the symbol
3511 FD_SETSIZE (currently 256), but that is somewhat smaller than the current
3512 kernel limit to the number of open files. However, in order to accommo-
3513 date programs which might potentially use a larger number of open files
3514 with select, it is possible to increase this size within a program by
3515 providing a larger definition of FD_SETSIZE before the inclusion of
3516 <sys/types.h>. The kernel will cope, and the userland libraries provided
3517 with the system are also ready for large numbers of file descriptors.
3519 Alternatively, to be really safe, it is possible to allocate fd_set bit-
3520 arrays dynamically. The idea is to permit a program to work properly
3521 even if it is execve(2)'d with 4000 file descriptors pre-allocated. The
3522 following illustrates the technique which is used by userland libraries:
3527 fdsr = (fd_set *)calloc(howmany(max+1, NFDBITS),
3534 n = select(max+1, fdsr, NULL, NULL, &tv);
3538 Alternatively, it is possible to use the poll(2) interface. poll(2) is
3539 more efficient when the size of select()'s fd_set bit-arrays are very
3540 large, and for fixed numbers of file descriptors one need not size and
3541 dynamically allocate a memory object.
3543 select() should probably have been designed to return the time remaining
3544 from the original timeout, if any, by modifying the time value in place.
3545 Even though some systems stupidly act in this different way, it is
3546 unlikely this semantic will ever be commonly implemented, as the change
3547 causes massive source code compatibility problems. Furthermore, recent
3548 new standards have dictated the current behaviour. In general, due to
3549 the existence of those brain-damaged non-conforming systems, it is unwise
3550 to assume that the timeout value will be unmodified by the select() call,
3551 and the caller should reinitialize it on each invocation. Calculating
3552 the delta is easily done by calling gettimeofday(2) before and after the
3553 call to select(), and using timersub() (as described in getitimer(2)).
3555 Internally to the kernel, select() works poorly if multiple processes
3556 wait on the same file descriptor. Given that, it is rather surprising to
3557 see that many daemons are written that way (i.e., httpd(8)).
3560 The select() function call appeared in 4.2BSD.
3562 BSD March 25, 1994 BSD
3566 <sect1 id="net-common-tcpip-manpages-send">
3569 SEND(2) BSD System Calls Manual SEND(2)
3572 send, sendto, sendmsg - send a message from a socket
3575 #include <sys/types.h>
3576 #include <sys/socket.h>
3579 send(int s, const void *msg, size_t len, int flags);
3582 sendto(int s, const void *msg, size_t len, int flags,
3583 const struct sockaddr *to, socklen_t tolen);
3586 sendmsg(int s, const struct msghdr *msg, int flags);
3589 send(), sendto(), and sendmsg() are used to transmit a message to another
3590 socket. send() may be used only when the socket is in a connected state,
3591 while sendto() and sendmsg() may be used at any time.
3593 The address of the target is given by to with tolen specifying its size.
3594 The length of the message is given by len. If the message is too long to
3595 pass atomically through the underlying protocol, the error EMSGSIZE is
3596 returned, and the message is not transmitted.
3598 No indication of failure to deliver is implicit in a send(). Locally
3599 detected errors are indicated by a return value of -1.
3601 If no messages space is available at the socket to hold the message to be
3602 transmitted, then send() normally blocks, unless the socket has been
3603 placed in non-blocking I/O mode. The select(2) or poll(2) system calls
3604 may be used to determine when it is possible to send more data.
3606 The flags parameter may include one or more of the following:
3608 #define MSG_OOB 0x1 /* process out-of-band data */
3609 #define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */
3611 The flag MSG_OOB is used to send ``out-of-band'' data on sockets that
3612 support this notion (e.g., SOCK_STREAM); the underlying protocol must
3613 also support ``out-of-band'' data. MSG_DONTROUTE is usually used only by
3614 diagnostic or routing programs.
3616 See recv(2) for a description of the msghdr structure.
3619 The call returns the number of characters sent, or -1 if an error
3623 send(), sendto(), and sendmsg() fail if:
3625 [EBADF] An invalid descriptor was specified.
3627 [ENOTSOCK] The argument s is not a socket.
3629 [EFAULT] An invalid user space address was specified for a
3632 [EMSGSIZE] The socket requires that message be sent atomically,
3633 and the size of the message to be sent made this
3636 [EAGAIN] The socket is marked non-blocking and the requested
3637 operation would block.
3639 [ENOBUFS] The system was unable to allocate an internal buffer.
3640 The operation may succeed when buffers become avail-
3643 [ENOBUFS] The output queue for a network interface was full.
3644 This generally indicates that the interface has
3645 stopped sending, but may be caused by transient con-
3648 [EACCES] The SO_BROADCAST option is not set on the socket, and
3649 a broadcast address was given as the destination.
3651 [EHOSTUNREACH] The destination address specified an unreachable host.
3653 [EINVAL] The flags parameter is invalid.
3655 [EHOSTDOWN] The destination address specified a host that is down.
3657 [ENETDOWN] The destination address specified a network that is
3660 [ECONNREFUSED] The destination host rejected the message (or a previ-
3661 ous one). This error can only be returned by con-
3664 [ENOPROTOOPT] There was a problem sending the message. This error
3665 can only be returned by connected sockets.
3667 [EDESTADDRREQ] The socket is not connected, and no destination
3668 address was specified.
3670 [EISCONN] The socket is already connected, and a destination
3671 address was specified.
3673 In addition, send() and sendto() may return the following error:
3675 [EINVAL] len was larger than SSIZE_MAX.
3677 Also, sendmsg() may return the following errors:
3679 [EINVAL] The sum of the iov_len values in the msg_iov array
3680 overflowed an ssize_t.
3682 [EMSGSIZE] The msg_iovlen member of msg was less than 0 or larger
3685 [EAFNOSUPPORT] Addresses in the specified address family cannot be
3686 used with this socket.
3689 fcntl(2), getsockopt(2), poll(2), recv(2), select(2), poll(2), socket(2),
3693 The send() function call appeared in 4.2BSD.
3695 BSD July 28, 1998 BSD
3699 <sect1 id="net-common-tcpip-manpages-shutdown">
3700 <title>shutdown</title>
3702 SHUTDOWN(2) BSD System Calls Manual SHUTDOWN(2)
3705 shutdown - shut down part of a full-duplex connection
3708 #include <sys/types.h>
3709 #include <sys/socket.h>
3712 shutdown(int s, int how);
3715 The shutdown() call causes all or part of a full-duplex connection on the
3716 socket associated with s to be shut down. If how is SHUT_RD, further
3717 receives will be disallowed. If how is SHUT_WR, further sends will be
3718 disallowed. If how is SHUT_RDWR, further sends and receives will be dis-
3722 A 0 is returned if the call succeeds, -1 if it fails.
3725 The call succeeds unless:
3727 [EINVAL] how is not SHUT_RD, SHUT_WR, or SHUT_RDWR.
3729 [EBADF] s is not a valid descriptor.
3731 [ENOTSOCK] s is a file, not a socket.
3733 [ENOTCONN] The specified socket is not connected.
3736 connect(2), socket(2)
3739 The shutdown() function call appeared in 4.2BSD. The how arguments used
3740 to be simply 0, 1, and 2, but now have named values as specified by
3741 X/Open Portability Guide Issue 4 (``XPG4'').
3743 BSD June 4, 1993 BSD
3747 <sect1 id="net-common-tcpip-manpages-socket">
3748 <title>socket</title>
3750 SOCKET(2) BSD System Calls Manual SOCKET(2)
3753 socket - create an endpoint for communication
3756 #include <sys/types.h>
3757 #include <sys/socket.h>
3760 socket(int domain, int type, int protocol);
3763 socket() creates an endpoint for communication and returns a descriptor.
3765 The domain parameter specifies a communications domain within which com-
3766 munication will take place; this selects the protocol family which should
3767 be used. These families are defined in the include file <sys/socket.h>.
3768 The currently understood formats are
3770 AF_UNIX (UNIX internal protocols),
3771 AF_INET (ARPA Internet protocols),
3772 AF_INET6 (ARPA IPv6 protocols),
3773 AF_ISO (ISO protocols),
3774 AF_NS (Xerox Network Systems protocols),
3775 AF_IPX (Internetwork Packet Exchange), and
3776 AF_IMPLINK (IMP host at IMP link layer).
3778 The socket has the indicated type, which specifies the semantics of com-
3779 munication. Currently defined types are:
3787 A SOCK_STREAM type provides sequenced, reliable, two-way connection based
3788 byte streams. An out-of-band data transmission mechanism may be sup-
3789 ported. A SOCK_DGRAM socket supports datagrams (connectionless, unreli-
3790 able messages of a fixed (typically small) maximum length). A
3791 SOCK_SEQPACKET socket may provide a sequenced, reliable, two-way connec-
3792 tion-based data transmission path for datagrams of fixed maximum length;
3793 a consumer may be required to read an entire packet with each read system
3794 call. This facility is protocol specific, and presently implemented only
3795 for PF_NS. SOCK_RAW sockets provide access to internal network protocols
3796 and interfaces. The types SOCK_RAW, which is available only to the supe-
3797 ruser, and SOCK_RDM, which is planned, but not yet implemented, are not
3800 The protocol specifies a particular protocol to be used with the socket.
3801 Normally only a single protocol exists to support a particular socket
3802 type within a given protocol family. However, it is possible that many
3803 protocols may exist, in which case a particular protocol must be speci-
3804 fied in this manner. The protocol number to use is particular to the
3805 communication domain in which communication is to take place; see
3806 protocols(5). A value of 0 for protocol will let the system select an
3807 appropriate protocol for the requested socket type.
3809 Sockets of type SOCK_STREAM are full-duplex byte streams, similar to
3810 pipes. A stream socket must be in a connected state before any data may
3811 be sent or received on it. A connection to another socket is created
3812 with a connect(2) call. Once connected, data may be transferred using
3813 read(2) and write(2) calls or some variant of the send(2) and recv(2)
3814 calls. When a session has been completed a close(2) may be performed.
3815 Out-of-band data may also be transmitted as described in send(2) and
3816 received as described in recv(2).
3818 The communications protocols used to implement a SOCK_STREAM ensure that
3819 data is not lost or duplicated. If a piece of data for which the peer
3820 protocol has buffer space cannot be successfully transmitted within a
3821 reasonable length of time, then the connection is considered broken and
3822 calls will indicate an error with -1 returns and with ETIMEDOUT as the
3823 specific code in the global variable errno. The protocols optionally
3824 keep sockets ``warm'' by forcing transmissions roughly every minute in
3825 the absence of other activity. An error is then indicated if no response
3826 can be elicited on an otherwise idle connection for a extended period
3827 (e.g., 5 minutes). A SIGPIPE signal is raised if a process sends on a
3828 broken stream; this causes naive processes, which do not handle the sig-
3831 SOCK_SEQPACKET sockets employ the same system calls as SOCK_STREAM sock-
3832 ets. The only difference is that read(2) calls will return only the
3833 amount of data requested, and any remaining in the arriving packet will
3836 SOCK_DGRAM and SOCK_RAW sockets allow sending of datagrams to correspon-
3837 dents named in send(2) calls. Datagrams are generally received with
3838 recvfrom(2), which returns the next datagram with its return address.
3840 An fcntl(2) call can be used to specify a process group to receive a
3841 SIGURG signal when the out-of-band data arrives. It may also enable non-
3842 blocking I/O and asynchronous notification of I/O events via SIGIO.
3844 The operation of sockets is controlled by socket level options. These
3845 options are defined in the file <sys/socket.h>. setsockopt(2) and
3846 getsockopt(2) are used to set and get options, respectively.
3849 A -1 is returned if an error occurs, otherwise the return value is a
3850 descriptor referencing the socket.
3853 The socket() call fails if:
3855 [EPROTONOSUPPORT] The protocol type or the specified protocol is not
3856 supported within this domain.
3858 [EMFILE] The per-process descriptor table is full.
3860 [ENFILE] The system file table is full.
3862 [EACCES] Permission to create a socket of the specified type
3863 and/or protocol is denied.
3865 [ENOBUFS] Insufficient buffer space is available. The socket
3866 cannot be created until sufficient resources are
3870 accept(2), bind(2), connect(2), getsockname(2), getsockopt(2), ioctl(2),
3871 listen(2), poll(2), read(2), recv(2), select(2), send(2), setsockopt(2),
3872 shutdown(2), socketpair(2), write(2), getprotoent(3), netintro(4)
3874 An Introductory 4.3 BSD Interprocess Communication Tutorial, reprinted in
3875 UNIX Programmer's Supplementary Documents Volume 1.
3877 BSD Interprocess Communication Tutorial, reprinted in UNIX Programmer's
3878 Supplementary Documents Volume 1.
3881 The socket() function call appeared in 4.2BSD.
3883 BSD June 4, 1993 BSD
3890 <!-- Keep this comment at the end of the file
3895 sgml-namecase-general:t
3896 sgml-general-insert-case:lower
3897 sgml-minimize-attributes:nil
3898 sgml-always-quote-attributes:t
3901 sgml-parent-document:("tcpip.sgml" "book" "chapter")
3902 sgml-exposed-tags:nil
3903 sgml-local-catalogs:nil
3904 sgml-local-ecat-files:nil
projects / karo-tx-redboot.git / blob