--- name: "coap_address" section: "3" platform: "linux" package: "libcoap3t64" version: "4.3.4-1.1+deb13u3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/coap_address" --- # coap\_address(3) Work with CoAP Socket Address Types ## NAME coap\_address, coap\_address\_t, coap\_address\_init, coap\_address\_copy, coap\_address\_equals, coap\_address\_get\_port, coap\_address\_set\_port, coap\_get\_available\_scheme\_hint\_bits, coap\_resolve\_address\_info, coap\_free\_address\_info, coap\_sockaddr\_un, coap\_address\_set\_unix\_domain, coap\_host\_is\_unix\_domain, coap\_is\_bcast, coap\_is\_mcast, coap\_is\_af\_unix - Work with CoAP Socket Address Types ## SYNOPSIS **#include \** **struct coap\_address\_t;** **struct coap\_sockaddr\_un;** **void coap\_address\_init(coap\_address\_t \****addr***);** **void coap\_address\_copy(coap\_address\_t \****dst***, const coap\_address\_t \****src***);** **int coap\_address\_equals(const coap\_address\_t \****a***, const coap\_address\_t \****b***);** **uint16\_t coap\_address\_get\_port(const coap\_address\_t \****addr***);** **void coap\_address\_set\_port(coap\_address\_t \****addr***, uint16\_t** *port***);** **uint32\_t coap\_get\_available\_scheme\_hint\_bits(int** *have\_pki\_psk***, int** *ws\_check***, coap\_proto\_t** *use\_unix\_proto***);** **coap\_addr\_info\_t \*coap\_resolve\_address\_info(const coap\_str\_const\_t \****address***, uint16\_t** *port***, uint16\_t** *secure\_port***, uint16\_t** *ws\_port***, uint16\_t** *ws\_secure\_port***, int** *ai\_hints\_flags***, int** *scheme\_hint\_bits***, coap\_resolve\_type\_t** *type***);** **void coap\_free\_address\_info(coap\_addr\_info\_t \****info\_list***);** **int coap\_host\_is\_unix\_domain(const coap\_str\_const\_t \****host***);** **int coap\_address\_set\_unix\_domain(coap\_address\_t \****addr***, const uint8\_t \****host***, size\_t** *host\_len***);** **int coap\_is\_bcast(const coap\_address\_t \****addr***);** **int coap\_is\_mcast(const coap\_address\_t \****addr***);** **int coap\_is\_af\_unix(const coap\_address\_t \****addr***);** For specific (D)TLS library support, link with **-lcoap-3-notls**, **-lcoap-3-gnutls**, **-lcoap-3-openssl**, **-lcoap-3-mbedtls** or **-lcoap-3-tinydtls**. Otherwise, link with **-lcoap-3** to get the default (D)TLS library support. ## DESCRIPTION This man page focuses on setting up CoAP endpoint address definitions. **Supported Socket Types** Libcoap supports 3 different socket types that can be used: ``` AF_INET IPv4 IP addresses and ports AF_INET6 IPv6 IP addresses and ports and can be dual IPv4/IPv6 stacked AF_UNIX Unix Domain using file path names ``` which are all handled by the **coap\_address\_t** structure. **Structure coap\_address\_t** ``` /* Multi-purpose address abstraction */ typedef struct coap_address_t { socklen_t size; /* size of addr */ union { struct sockaddr sa; struct sockaddr_in sin; struct sockaddr_in6 sin6; struct coap_sockaddr_un cun; /* CoAP shortened special */ } addr; } coap_address_t; which is used in the *coap_addr_info_t* structure as returned by *coap_resolve_address_info()*. ``` **Structure coap\_addr\_info\_t** ``` /* Resolved addresses information */ typedef struct coap_addr_info_t { struct coap_addr_info_t *next; /* Next entry in the chain */ coap_uri_scheme_t scheme; /* CoAP scheme to use */ coap_proto_t proto; /* CoAP protocol to use */ coap_address_t addr; /* The address to connect / bind to */ } coap_addr_info_t; ``` **Structure coap\_sockaddr\_un** ``` #define COAP_UNIX_PATH_MAX (sizeof(struct sockaddr_in6) - sizeof(sa_family_t)) struct coap_sockaddr_un { sa_family_t sun_family; /* AF_UNIX */ char sun_path[COAP_UNIX_PATH_MAX]; /* pathname max 26 with NUL byte */ }; ``` The **coap\_sockaddr\_un** structure is modeled on the **sockaddr\_un** structure (see [**unix**(7)](/unix/7.md)) but has a smaller sun\_path so that the overall size of **coap\_address\_t** is not changed by its inclusion. COAP\_UNIX\_MAX\_PATH includes the trailing zero terminator of a domain unix file name. **Enum coap\_resolve\_type\_t** ``` typedef enum coap_resolve_type_t { COAP_RESOLVE_TYPE_LOCAL, /* local side of session */ COAP_RESOLVE_TYPE_REMOTE, /* remote side of session */ } coap_resolve_type_t; ``` Used when determining how to do an address lookup when calling **coap\_resolve\_address\_info()**. ## FUNCTIONS **Function: coap\_address\_init()** The **coap\_address\_init**() function initializes *addr* for later use. In particular it sets the *size* variable and sets all other values to be 0. It is then the responsibility of the application to set the address family in addr.sa.sa\_family and then fill in the the appropriate union structure based on the address family before the coap\_address\_t *addr* is used. **Function: coap\_address\_copy()** The **coap\_address\_copy**() function copies the address *src* into *dst*. **Function: coap\_address\_equals()** The **coap\_address\_equals**() function checks whether the addresses *a* and *b* are identical. **Function: coap\_address\_get\_port()** The **coap\_address\_get\_port**() function gets the the port from *addr* if *addr* is AF\_INET or AF\_INET6. **Function: coap\_address\_set\_port()** The **coap\_address\_set\_port**() function sets the the *port* in *addr* if *addr* is AF\_INET or AF\_INET6. **Function: coap\_get\_available\_scheme\_hint\_bits()** The **coap\_get\_available\_scheme\_hint\_bits**() function is used for servers to determine what coap schemes are supported in the underlying libcoap library. *have\_pki\_psk* can be set to 1 to check for (D)DTLS support, else 0. *ws\_check* can be set to 1 to check for WebSockets support, else 0. *use\_unix\_proto*, if not set to COAP\_PROTO\_NONE, hints at the specific CoAP protocol to use over a Unix socket. The output is suitable for input for the **coap\_address\_resolve\_info**()'s *scheme\_hint\_bits*. **Function: coap\_resolve\_address\_info()** The **coap\_resolve\_address\_info**() function resolves the address *address* into a set of one or more coap\_addr\_info\_t structures. Depending on the scheme as abstracted from *scheme\_hint\_bits*, *port*, *secure\_port*, *ws\_port* (WebSockets) or *ws\_secure\_port* (WebSockets) is used to update the addr variable of coap\_addr\_info\_t. If *port* (or *secure\_port*) is 0, then the default port for the scheme is used if *type* is set to COAP\_RESOLVE\_TYPE\_LOCAL. *ai\_hints\_flags* is used for the internally called [getaddrinfo(3)](/getaddrinfo/3.md) function. *scheme\_hint\_bits* is a set of one or more COAP\_URI\_SCHEME\_\**BIT or’d together. \_scheme\_hint\_bits* can also (for servers) be the output from **coap\_get\_available\_scheme\_hint\_bits**(). The returned set of coap\_addr\_info\_t structures must be freed off by the caller using **coap\_free\_address\_info**(). **Function: coap\_free\_address\_info()** The **coap\_free\_address\_info**() function frees off all the *info\_list* linked entries. **Function: coap\_address\_set\_unix\_domain()** The **coap\_address\_set\_unix\_domain**() function initializes *addr* and then populates *addr* with all the appropriate information for a Unix Domain Socket. The *host* information with length *host\_len* abstracted from a CoAP URI is copied into *addr*'s *sun\_path* translating any %2F encoding to /. **Function: coap\_host\_is\_unix\_domain()** The **coap\_host\_is\_unix\_domain**() function checks whether *host* is an an AF\_UNIX file name (encoded using %2F to indicate a /). **Function: coap\_is\_mcast()** The **coap\_is\_mcast**() function checks whether *addr* is a multicast address. **Function: coap\_is\_bcast()** The **coap\_is\_mcast**() function checks whether *addr* is a broadcast address. **Function: coap\_is\_af\_unix()** The **coap\_is\_mcast**() function checks whether *addr* is of the type AF\_UNIX. ## RETURN VALUES **coap\_address\_equals**() returns 1 if the addresses are equal or 0 if not. **coap\_address\_get\_port**() returns the port in network byte order. **coap\_get\_available\_scheme\_hint\_bits**() returns a set of COAP\_URI\_SCHEME\_\*\_BIT or’d together based on the supported libcoap functionality. **coap\_resolve\_address\_info**() returns a linked list of addresses that can be used for session setup or NULL if there is a failure. **coap\_address\_set\_unix\_domain**() returns 1 on success or 0 on failure. **coap\_host\_is\_unix\_domain**() returns 1 if encoded unix path name or 0 if not. **coap\_is\_mcast**() returns 1 if address is multicast or 0 if not. **coap\_is\_bcast**() returns 1 if address is broadcast or 0 if not. **coap\_is\_af\_unix**() returns 1 if address is of type AF\_UNIX or 0 if not. ## EXAMPLES **Get client target address from uri** ``` #include static int get_address(coap_uri_t *uri, coap_address_t *dst) { coap_addr_info_t *info_list; info_list = coap_resolve_address_info(&uri->host, uri->port, uri->port, uri->port, uri->port,0, 1 << uri->scheme, COAP_RESOLVE_TYPE_LOCAL); if (info_list == NULL) return 0; memcpy(dst, &info_list->addr, sizeof(*dst)); coap_free_address_info(info_list); return 1; } ``` ## SEE ALSO [**coap\_endpoint\_client**(3)](/coap_endpoint_client/3.md), [**coap\_endpoint\_server**(3)](/coap_endpoint_server/3.md) and [**coap\_uri**(3)](/coap_uri/3.md) ## FURTHER INFORMATION See "RFC7252: The Constrained Application Protocol (CoAP)" for further information. ## BUGS Please report bugs on the mailing list for libcoap: libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at https://github.com/obgm/libcoap/issues ## AUTHORS The libcoap project \