--- name: "lwres_getaddrinfo" section: "3" platform: "macos" package: "bind9" version: "65" release: "macOS 26.5" platforms: ["linux", "macos"] url: "https://new.carta.tech/lwres_getaddrinfo" --- # lwres\_getaddrinfo(3) socket address structure to host and service name ## NAME lwres\_getaddrinfo, lwres\_freeaddrinfo - socket address structure to host and service name ## SYNOPSIS ``` #include ``` **int lwres\_getaddrinfo(const char \****hostname***, const char \****servname***, const struct addrinfo \****hints***, struct addrinfo \*\****res***);** **void lwres\_freeaddrinfo(struct addrinfo \****ai***);** If the operating system does not provide a **struct addrinfo**, the following structure is used: ``` struct addrinfo { int ai_flags; /* AI_PASSIVE, AI_CANONNAME */ int ai_family; /* PF_xxx */ int ai_socktype; /* SOCK_xxx */ int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ size_t ai_addrlen; /* length of ai_addr */ char *ai_canonname; /* canonical name for hostname */ struct sockaddr *ai_addr; /* binary address */ struct addrinfo *ai_next; /* next structure in linked list */ }; ``` ## DESCRIPTION **lwres\_getaddrinfo()** is used to get a list of IP addresses and port numbers for host *hostname* and service *servname*. The function is the lightweight resolver's implementation of **getaddrinfo()** as defined in RFC2133. *hostname* and *servname* are pointers to null-terminated strings or **NULL**. *hostname* is either a host name or a numeric host address string: a dotted decimal IPv4 address or an IPv6 address. *servname* is either a decimal port number or a service name as listed in /etc/services. *hints* is an optional pointer to a **struct addrinfo**. This structure can be used to provide hints concerning the type of socket that the caller supports or wishes to use. The caller can supply the following structure elements in *\*hints*: **ai\_family** The protocol family that should be used. When **ai\_family** is set to **PF\_UNSPEC**, it means the caller will accept any protocol family supported by the operating system. **ai\_socktype** denotes the type of socket — **SOCK\_STREAM**, **SOCK\_DGRAM** or **SOCK\_RAW** — that is wanted. When **ai\_socktype** is zero the caller will accept any socket type. **ai\_protocol** indicates which transport protocol is wanted: IPPROTO\_UDP or IPPROTO\_TCP. If **ai\_protocol** is zero the caller will accept any protocol. **ai\_flags** Flag bits. If the **AI\_CANONNAME** bit is set, a successful call to **lwres\_getaddrinfo()** will return a null-terminated string containing the canonical name of the specified hostname in **ai\_canonname** of the first **addrinfo** structure returned. Setting the **AI\_PASSIVE** bit indicates that the returned socket address structure is intended for used in a call to [**bind**(2)](/bind/2.md). In this case, if the hostname argument is a **NULL** pointer, then the IP address portion of the socket address structure will be set to **INADDR\_ANY** for an IPv4 address or **IN6ADDR\_ANY\_INIT** for an IPv6 address. When **ai\_flags** does not set the **AI\_PASSIVE** bit, the returned socket address structure will be ready for use in a call to [**connect**(2)](/connect/2.md) for a connection-oriented protocol or [**connect**(2)](/connect/2.md), [**sendto**(2)](/sendto/2.md), or [**sendmsg**(2)](/sendmsg/2.md) if a connectionless protocol was chosen. The IP address portion of the socket address structure will be set to the loopback address if *hostname* is a **NULL** pointer and **AI\_PASSIVE** is not set in **ai\_flags**. If **ai\_flags** is set to **AI\_NUMERICHOST** it indicates that *hostname* should be treated as a numeric string defining an IPv4 or IPv6 address and no name resolution should be attempted. All other elements of the **struct addrinfo** passed via *hints* must be zero. A *hints* of **NULL** is treated as if the caller provided a **struct addrinfo** initialized to zero with **ai\_family**set to **PF\_UNSPEC**. After a successful call to **lwres\_getaddrinfo()**, *\*res* is a pointer to a linked list of one or more **addrinfo** structures. Each **struct addrinfo** in this list cn be processed by following the **ai\_next** pointer, until a **NULL** pointer is encountered. The three members **ai\_family**, **ai\_socktype**, and **ai\_protocol** in each returned **addrinfo** structure contain the corresponding arguments for a call to [**socket**(2)](/socket/2.md). For each **addrinfo** structure in the list, the **ai\_addr** member points to a filled-in socket address structure of length **ai\_addrlen**. All of the information returned by **lwres\_getaddrinfo()** is dynamically allocated: the addrinfo structures, and the socket address structures and canonical host name strings pointed to by the **addrinfo**structures. Memory allocated for the dynamically allocated structures created by a successful call to **lwres\_getaddrinfo()** is released by **lwres\_freeaddrinfo()**. *ai* is a pointer to a **struct addrinfo** created by a call to **lwres\_getaddrinfo()**. ## RETURN VALUES **lwres\_getaddrinfo()** returns zero on success or one of the error codes listed in [**gai\_strerror**(3)](/gai_strerror/3.md) if an error occurs. If both *hostname* and *servname* are **NULLlwres\_getaddrinfo()** returns **EAI\_NONAME**. ## SEE ALSO [**lwres**(3)](/lwres/3.md), [**lwres\_getaddrinfo**(3)](/lwres_getaddrinfo/3.md), [**lwres\_freeaddrinfo**(3)](/lwres_freeaddrinfo/3.md), [**lwres\_gai\_strerror**(3)](/lwres_gai_strerror/3.md), **RFC2133**(), [**getservbyname**(3)](/getservbyname/3.md), [**bind**(2)](/bind/2.md), [**connect**(2)](/connect/2.md), [**sendto**(2)](/sendto/2.md), [**sendmsg**(2)](/sendmsg/2.md), [**socket**(2)](/socket/2.md). ## AUTHOR **Internet Systems Consortium, Inc.** ## COPYRIGHT Copyright © 2004, 2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")\ Copyright © 2000, 2001, 2003 Internet Software Consortium.\