netinet_in.h(7POSIX)

📦 version 2017a, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

🌸 netinet_in.h(7POSIX) 🌸

okay bestie, so this page is literally straight out of the POSIX Programmer's Manual, and it's all about <netinet/in.h> — the header that runs the whole Internet address family situation. 💅

💖 PROLOG 💖

This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (so like, go consult the corresponding Linux manual page for the tea on Linux behavior, fr), or the interface may not be implemented on Linux at all. 🙈

✨ NAME ✨

netinet/in.h — Internet address family. that's it, that's the name, iconic behavior honestly 👑

🦋 SYNOPSIS 🦋

#include <netinet/in.h>

💜 DESCRIPTION 💜

okay so the <netinet/in.h> header shall define these types, no debate:

  • in_port_t — Equivalent to the type uint16_t as described in <inttypes.h>.
  • in_addr_t — Equivalent to the type uint32_t as described in <inttypes.h>.

The <netinet_in.h> header shall define the sa_family_t type as described in <sys/socket.h>.

The <netinet_in.h> header shall define the uint8_t and uint32_t types as described in <inttypes.h>. Also, heads up — including the <netinet/in.h> header may also make visible all symbols from <inttypes.h> and <sys/socket.h>. so like, bonus content, no cap.

🎀 the in_addr structure 🎀

The <netinet/in.h> header shall define the in_addr structure, which shall include at least this member:

in_addr_t  s_addr

🎀 the sockaddr_in structure 🎀

The <netinet/in.h> header shall define the sockaddr_in structure, which shall include at least these members:

sa_family_t     sin_family   AF_INET.
in_port_t       sin_port     Port number.
struct in_addr  sin_addr     IP address.

The sin_port and sin_addr members shall be in network byte order. don't forget that part, it's giving "important" 🔥

The sockaddr_in structure is used to store addresses for the Internet address family. Pointers to this type shall be cast by applications to struct sockaddr * for use with socket functions.

🎀 the in6_addr structure 🎀

The <netinet/in.h> header shall define the in6_addr structure, which shall include at least this member:

uint8_t s6_addr[16]

This array is used to contain a 128-bit IPv6 address, stored in network byte order.

🎀 the sockaddr_in6 structure 🎀

The <netinet/in.h> header shall define the sockaddr_in6 structure, which shall include at least these members:

sa_family_t      sin6_family    AF_INET6.
in_port_t        sin6_port      Port number.
uint32_t         sin6_flowinfo  IPv6 traffic class and flow information.
struct in6_addr  sin6_addr      IPv6 address.
uint32_t         sin6_scope_id  Set of interfaces for a scope.

The sin6_port and sin6_addr members shall be in network byte order. same energy as before 💅

⚠️ okay this next part is a whole paragraph and you NEED it: Prior to calling a function in this standard which reads values from a sockaddr_in6 structure (for example, bind() or connect()), the application shall ensure that all members of the structure, including any additional non-standard members, if any, are initialized. If the sockaddr_in6 structure has a non-standard member, and that member has a value other than the value that would result from default initialization, the behavior of any function in this standard that reads values from the sockaddr_in6 structure is implementation-defined. All functions in this standard that return data in a sockaddr_in6 structure (for example, getaddrinfo() or accept()) shall initialize the structure in a way that meets the above requirements, and shall ensure that each non-standard member, if any, has a value that produces the same behavior as default initialization would in all functions in this standard which read values from a sockaddr_in6 structure. 😭 it's a lot but it matters

The sin6_scope_id field is a 32-bit integer that identifies a set of interfaces as appropriate for the scope of the address carried in the sin6_addr field. For a link scope sin6_addr, the application shall ensure that sin6_scope_id is a link index. For a site scope sin6_addr, the application shall ensure that sin6_scope_id is a site index. The mapping of sin6_scope_id to an interface or set of interfaces is implementation-defined.

🎀 external variables 🎀

The <netinet/in.h> header shall declare this external variable:

const struct in6_addr in6addr_any

This variable is initialized by the system to contain the wildcard IPv6 address. The <netinet/in.h> header also defines the IN6ADDR_ANY_INIT macro. This macro must be constant at compile time and can be used to initialize a variable of type struct in6_addr to the IPv6 wildcard address.

The <netinet/in.h> header shall declare this external variable too:

const struct in6_addr in6addr_loopback

This variable is initialized by the system to contain the loopback IPv6 address. The <netinet/in.h> header also defines the IN6ADDR_LOOPBACK_INIT macro. This macro must be constant at compile time and can be used to initialize a variable of type struct in6_addr to the IPv6 loopback address.

🎀 the ipv6_mreq structure 🎀

The <netinet/in.h> header shall define the ipv6_mreq structure, which shall include at least these members:

struct in6_addr  ipv6mr_multiaddr  IPv6 multicast address.
unsigned         ipv6mr_interface  Interface index.

🎀 symbolic constants for the level argument 🎀

The <netinet/in.h> header shall define these symbolic constants for use as values of the level argument of getsockopt() and setsockopt():

  • IPPROTO_IP — Internet protocol.
  • IPPROTO_IPV6 — Internet Protocol Version 6.
  • IPPROTO_ICMP — Control message protocol.
  • IPPROTO_RAW — Raw IP Packets Protocol.
  • IPPROTO_TCP — Transmission control protocol.
  • IPPROTO_UDP — User datagram protocol.

🎀 INADDR_ANY 🎀

The <netinet/in.h> header shall define this symbolic constant for use as a local address in the structure passed to bind():

  • INADDR_ANY — IPv4 wildcard address.

🎀 INADDR_BROADCAST 🎀

The <netinet/in.h> header shall define this symbolic constant for use as a destination address in the structures passed to connect(), sendmsg(), and sendto():

  • INADDR_BROADCAST — IPv4 broadcast address.

🎀 INET_ADDRSTRLEN 🎀

The <netinet/in.h> header shall define this symbolic constant, with the value specified, to help applications declare buffers of the proper size to store IPv4 addresses in string form:

  • INET_ADDRSTRLEN — 16. Length of the string form for IP.

🎀 the byte-order girlies 🎀

The htonl(), htons(), ntohl(), and ntohs() functions shall be available as described in <arpa/inet.h>. Inclusion of the <netinet/in.h> header may also make visible all symbols from <arpa/inet.h>. 🦋

🎀 INET6_ADDRSTRLEN 🎀

The <netinet/in.h> header shall define this symbolic constant, with the value specified, to help applications declare buffers of the proper size to store IPv6 addresses in string form:

  • INET6_ADDRSTRLEN — 46. Length of the string form for IPv6.

🎀 IPv6 socket option constants 🎀

The <netinet/in.h> header shall define these symbolic constants, with distinct integer values, for use in the option_name argument in the getsockopt() or setsockopt() functions at protocol level IPPROTO_IPV6:

  • IPV6_JOIN_GROUP — Join a multicast group.
  • IPV6_LEAVE_GROUP — Quit a multicast group.
  • IPV6_MULTICAST_HOPS — Multicast hop limit.
  • IPV6_MULTICAST_IF — Interface to use for outgoing multicast packets.
  • IPV6_MULTICAST_LOOP — Multicast packets are delivered back to the local application.
  • IPV6_UNICAST_HOPS — Unicast hop limit.
  • IPV6_V6ONLY — Restrict AF_INET6 socket to IPv6 communications only.

🎀 the IN6_IS_ADDR_* macros 🎀

The <netinet/in.h> header shall define these macros that test for special IPv6 addresses. Each macro is of type int and takes a single argument of type const struct in6_addr *:

  • IN6_IS_ADDR_UNSPECIFIED — Unspecified address.
  • IN6_IS_ADDR_LOOPBACK — Loopback address.
  • IN6_IS_ADDR_MULTICAST — Multicast address.
  • IN6_IS_ADDR_LINKLOCAL — Unicast link-local address.
  • IN6_IS_ADDR_SITELOCAL — Unicast site-local address.
  • IN6_IS_ADDR_V4MAPPED — IPv4 mapped address.
  • IN6_IS_ADDR_V4COMPAT — IPv4-compatible address.
  • IN6_IS_ADDR_MC_NODELOCAL — Multicast node-local address.
  • IN6_IS_ADDR_MC_LINKLOCAL — Multicast link-local address.
  • IN6_IS_ADDR_MC_SITELOCAL — Multicast site-local address.
  • IN6_IS_ADDR_MC_ORGLOCAL — Multicast organization-local address.
  • IN6_IS_ADDR_MC_GLOBAL — Multicast global address.

The following sections are informative. 👀

💖 APPLICATION USAGE 💖

so, even though applications are required to initialize all members (including any non-standard ones) of a sockaddr_in6 structure, the same is not required for the sockaddr_in structure, since historically many applications only initialized the standard members. Despite this, applications are encouraged to initialize sockaddr_in structures in a manner similar to the required initialization of sockaddr_in6 structures. do it bestie, it's the move 🫶

Even though it's super common practice to initialize a sockaddr_in6 structure like this:

struct sockaddr_in6 sa;
memset(&sa, 0, sizeof sa);

...this method is not portable according to this standard, because the structure can contain pointer or floating-point members that are not required to have an all-bits-zero representation after default initialization. 😭

Portable methods make use of default initialization; for example:

struct sockaddr_in6 sa = { 0 };

or:

static struct sockaddr_in6 sa_init;
struct sockaddr_in6 sa = sa_init;

A future version of this standard may require that a pointer object with an all-bits-zero representation is a null pointer, and that sockaddr_in6 does not have any floating-point members if a floating-point object with an all-bits-zero representation does not have the value 0.0. so like, watch this space 👀

🌈 RATIONALE 🌈

The INADDR_ANY and INADDR_BROADCAST values are byte-order-neutral and thus their byte order is not specified. Many implementations have additional constants as extensions, such as INADDR_LOOPBACK, that are not byte-order-neutral. Traditionally, these constants are in host byte order, requiring the use of htonl() when using them in a sockaddr_in structure. so remember to call your htonl(), babes 💅

⭐ FUTURE DIRECTIONS ⭐

None.

💜 SEE ALSO 💜

  • Section 4.10, Host and Network Byte Orders
  • <arpa_inet.h>
  • <inttypes.h>
  • <sys_socket.h>

The System Interfaces volume of POSIX.1‐2017:

  • connect()
  • getsockopt()
  • htonl()
  • sendmsg()
  • sendto()
  • setsockopt()

okay bestie, this is the part where the manpage gets all legal on us, and honestly? iconic of it. 💅 so here's the tea:

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. 🫶

and like, lowkey important: if this version and the original IEEE / The Open Group Standard ever beef with each other and don't match up? 👀 the original IEEE and The Open Group Standard is the referee document. no cap. it's the main character, this page is just the vibe. ✨

you can go get the original Standard online at http://www.opengroup.org/unix/online.html .

🎀 also fr fr — any typographical or formatting errors you spot in this page are most likely to have been introduced during the conversion of the source files to man page format. not the standard's fault, it's giving ✨conversion✨. to report those errors, go here: https://www.kernel.org/doc/man-pages/reporting_bugs.html

and that's a wrap on netinet_in.h(7POSIX), bestie!! 🦋 you made it to the end, slay. this little masterpiece comes to you from IEEE/The Open Group, dated 2017, and yeah the copyright block is giving homework but we got through it together 💜 periodt ✨👑

📦 where this page comes from