netlib Network support library

The netlib library provides a collection of network utility functions for managing network interfaces, IP addresses, routing tables, and other network-related operations. These functions are defined in netutils/netlib.h and are intended for internal use by NuttX applications.

Device Management

ssize_t netlib_get_devices(struct netlib_device_s *devlist, unsigned int nentries, sa_family_t family)

Get a list of all network devices.

Parameters:

  • devlist – Pointer to an array of netlib_device_s structures to receive the device list.

  • nentries – Maximum number of entries in the array.

  • family – Address family filter (AF_INET, AF_INET6, or AF_UNSPEC for all).

Returns:

Number of devices returned on success; -1 on error with errno set appropriately.

Address Conversion Functions

bool netlib_ipv4addrconv(const char *addrstr, uint8_t *addr)

Convert a textual representation of an IPv4 address to a numerical representation. This function takes an IP address in the form a.b.c.d and converts it into a 4-byte array.

Parameters:

  • addrstr – A pointer to a string containing the IP address in textual form.

  • addr – A pointer to a 4-byte array that will be filled with the numerical representation of the address.

Returns:

true if the IP address was parsed successfully; false otherwise.

bool netlib_ethaddrconv(const char *hwstr, uint8_t *hw)

Convert a textual representation of an Ethernet MAC address to a numerical representation.

Parameters:

  • hwstr – A pointer to a string containing the MAC address in textual form (e.g., "00:11:22:33:44:55").

  • hw – A pointer to a byte array that will be filled with the numerical representation of the MAC address.

Returns:

true if the MAC address was parsed successfully; false otherwise.

MAC Address Management

int netlib_setmacaddr(const char *ifname, const uint8_t *macaddr)

Set the MAC address for an Ethernet network interface.

Parameters:

  • ifname – Network interface name (e.g., "eth0").

  • macaddr – Pointer to a 6-byte array containing the MAC address.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_getmacaddr(const char *ifname, uint8_t *macaddr)

Get the MAC address of an Ethernet network interface.

Parameters:

  • ifname – Network interface name (e.g., "eth0").

  • macaddr – Pointer to a 6-byte array to receive the MAC address.

Returns:

0 on success; -1 on error with errno set appropriately.

IPv4 Address Management

int netlib_set_ipv4addr(const char *ifname, const struct in_addr *addr)

Set the IPv4 address for a network interface.

Parameters:

  • ifname – Network interface name (e.g., "eth0").

  • addr – Pointer to an in_addr structure containing the IPv4 address.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_get_ipv4addr(const char *ifname, struct in_addr *addr)

Get the IPv4 address of a network interface.

Parameters:

  • ifname – Network interface name (e.g., "eth0").

  • addr – Pointer to an in_addr structure to receive the IPv4 address.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_set_dripv4addr(const char *ifname, const struct in_addr *addr)

Set the default router (gateway) IPv4 address for a network interface.

Parameters:

  • ifname – Network interface name (e.g., "eth0").

  • addr – Pointer to an in_addr structure containing the gateway address.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_get_dripv4addr(const char *ifname, struct in_addr *addr)

Get the default router (gateway) IPv4 address of a network interface.

Parameters:

  • ifname – Network interface name (e.g., "eth0").

  • addr – Pointer to an in_addr structure to receive the gateway address.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_set_ipv4netmask(const char *ifname, const struct in_addr *addr)

Set the IPv4 netmask for a network interface.

Parameters:

  • ifname – Network interface name (e.g., "eth0").

  • addr – Pointer to an in_addr structure containing the netmask.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_get_ipv4netmask(const char *ifname, struct in_addr *addr)

Get the IPv4 netmask of a network interface.

Parameters:

  • ifname – Network interface name (e.g., "eth0").

  • addr – Pointer to an in_addr structure to receive the netmask.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_ipv4adaptor(in_addr_t destipaddr, in_addr_t *srcipaddr)

Find the appropriate source IPv4 address to use for communicating with a destination address.

Parameters:

  • destipaddr – Destination IPv4 address (in network byte order).

  • srcipaddr – Pointer to receive the source IPv4 address.

Returns:

0 on success; -1 on error with errno set appropriately.

IPv6 Address Management

int netlib_set_ipv6addr(const char *ifname, const struct in6_addr *addr)

Set the IPv6 address for a network interface.

Parameters:

  • ifname – Network interface name (e.g., "eth0"). Can include slot number for multiple addresses (e.g., "eth0:0").

  • addr – Pointer to an in6_addr structure containing the IPv6 address.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_get_ipv6addr(const char *ifname, struct in6_addr *addr)

Get the IPv6 address of a network interface.

Parameters:

  • ifname – Network interface name (e.g., "eth0"). Can include slot number for multiple addresses (e.g., "eth0:0").

  • addr – Pointer to an in6_addr structure to receive the IPv6 address.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_add_ipv6addr(const char *ifname, const struct in6_addr *addr, uint8_t preflen)

Add an IPv6 address to a network interface. This function is recommended for managing multiple IPv6 addresses on a single interface.

Parameters:

  • ifname – Network interface name (e.g., "eth0").

  • addr – Pointer to an in6_addr structure containing the IPv6 address.

  • preflen – Prefix length (0-128).

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_del_ipv6addr(const char *ifname, const struct in6_addr *addr, uint8_t preflen)

Remove an IPv6 address from a network interface.

Parameters:

  • ifname – Network interface name (e.g., "eth0").

  • addr – Pointer to an in6_addr structure containing the IPv6 address to remove.

  • preflen – Prefix length (0-128).

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_set_dripv6addr(const char *ifname, const struct in6_addr *addr)

Set the default router (gateway) IPv6 address for a network interface.

Parameters:

  • ifname – Network interface name (e.g., "eth0").

  • addr – Pointer to an in6_addr structure containing the gateway address.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_set_ipv6netmask(const char *ifname, const struct in6_addr *addr)

Set the IPv6 netmask for a network interface.

Parameters:

  • ifname – Network interface name (e.g., "eth0").

  • addr – Pointer to an in6_addr structure containing the netmask.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_ipv6adaptor(const struct in6_addr *destipaddr, struct in6_addr *srcipaddr)

Find the appropriate source IPv6 address to use for communicating with a destination address.

Parameters:

  • destipaddr – Pointer to the destination IPv6 address.

  • srcipaddr – Pointer to receive the source IPv6 address.

Returns:

0 on success; -1 on error with errno set appropriately.

uint8_t netlib_ipv6netmask2prefix(const uint16_t *mask)

Convert an IPv6 netmask to a prefix length.

Parameters:

  • mask – Pointer to a 16-bit array representing the netmask.

Returns:

Prefix length (0-128).

void netlib_prefix2ipv6netmask(uint8_t preflen, struct in6_addr *netmask)

Convert a prefix length to an IPv6 netmask.

Parameters:

  • preflen – Prefix length (0-128).

  • netmask – Pointer to an in6_addr structure to receive the netmask.

Network Interface Management

int netlib_getifstatus(const char *ifname, uint8_t *flags)

Get the status flags of a network interface.

Parameters:

  • ifname – Network interface name (e.g., "eth0").

  • flags – Pointer to receive the interface flags.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_ifup(const char *ifname)

Bring a network interface up (activate it).

Parameters:

  • ifname – Network interface name (e.g., "eth0").

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_ifdown(const char *ifname)

Bring a network interface down (deactivate it).

Parameters:

  • ifname – Network interface name (e.g., "eth0").

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_set_mtu(const char *ifname, int mtu)

Set the Maximum Transmission Unit (MTU) for a network interface.

Parameters:

  • ifname – Network interface name (e.g., "eth0").

  • mtu – MTU value in bytes.

Returns:

0 on success; -1 on error with errno set appropriately.

ARP Table Support

int netlib_set_arpmapping(const struct sockaddr_in *inaddr, const uint8_t *macaddr, const char *ifname)

Add or update an ARP table entry mapping an IPv4 address to a MAC address.

Parameters:

  • inaddr – Pointer to a sockaddr_in structure containing the IPv4 address.

  • macaddr – Pointer to a 6-byte array containing the MAC address.

  • ifname – Network interface name (e.g., "eth0"), or NULL for any interface.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_get_arpmapping(const struct sockaddr_in *inaddr, uint8_t *macaddr, const char *ifname)

Retrieve the MAC address associated with an IPv4 address from the ARP table.

Parameters:

  • inaddr – Pointer to a sockaddr_in structure containing the IPv4 address.

  • macaddr – Pointer to a 6-byte array to receive the MAC address.

  • ifname – Network interface name (e.g., "eth0"), or NULL for any interface.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_del_arpmapping(const struct sockaddr_in *inaddr, const char *ifname)

Delete an entry from the ARP table.

Parameters:

  • inaddr – Pointer to a sockaddr_in structure containing the IPv4 address.

  • ifname – Network interface name (e.g., "eth0"), or NULL for any interface.

Returns:

0 on success; -1 on error with errno set appropriately.

ssize_t netlib_get_arptable(struct arpreq *arptab, unsigned int nentries)

Retrieve the entire ARP table.

Parameters:

  • arptab – Pointer to an array of arpreq structures to receive the ARP table entries.

  • nentries – Maximum number of entries in the array.

Returns:

Number of entries returned on success; -1 on error with errno set appropriately.

Routing Table Support

int netlib_ipv4router(const struct in_addr *destipaddr, struct in_addr *router)

Find the router (gateway) address to use for reaching a destination IPv4 address.

Parameters:

  • destipaddr – Pointer to the destination IPv4 address.

  • router – Pointer to receive the router IPv4 address.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_ipv6router(const struct in6_addr *destipaddr, struct in6_addr *router)

Find the router (gateway) address to use for reaching a destination IPv6 address.

Parameters:

  • destipaddr – Pointer to the destination IPv6 address.

  • router – Pointer to receive the router IPv6 address.

Returns:

0 on success; -1 on error with errno set appropriately.

FILE *netlib_open_ipv4route(void)

Open the IPv4 routing table for reading. This is a macro that opens /proc/net/route/ipv4.

Returns:

File pointer on success; NULL on error.

void netlib_close_ipv4route(FILE *stream)

Close the IPv4 routing table file. This is a macro that calls fclose().

Parameters:

  • stream – File pointer returned by netlib_open_ipv4route().

ssize_t netlib_read_ipv4route(FILE *stream, struct netlib_ipv4_route_s *route)

Read one entry from the IPv4 routing table.

Parameters:

  • stream – File pointer returned by netlib_open_ipv4route().

  • route – Pointer to a netlib_ipv4_route_s structure to receive the route entry.

Returns:

1 on success; 0 on end of file; -1 on error.

FILE *netlib_open_ipv6route(void)

Open the IPv6 routing table for reading. This is a macro that opens /proc/net/route/ipv6.

Returns:

File pointer on success; NULL on error.

void netlib_close_ipv6route(FILE *stream)

Close the IPv6 routing table file. This is a macro that calls fclose().

Parameters:

  • stream – File pointer returned by netlib_open_ipv6route().

ssize_t netlib_read_ipv6route(FILE *stream, struct netlib_ipv6_route_s *route)

Read one entry from the IPv6 routing table.

Parameters:

  • stream – File pointer returned by netlib_open_ipv6route().

  • route – Pointer to a netlib_ipv6_route_s structure to receive the route entry.

Returns:

1 on success; 0 on end of file; -1 on error.

ssize_t netlib_get_route(struct rtentry *rtelist, unsigned int nentries, sa_family_t family)

Retrieve routing table entries using Netlink.

Parameters:

  • rtelist – Pointer to an array of rtentry structures to receive the routing entries.

  • nentries – Maximum number of entries in the array.

  • family – Address family filter (AF_INET, AF_INET6, or AF_UNSPEC for all).

Returns:

Number of entries returned on success; -1 on error with errno set appropriately.

DHCP Support

int netlib_obtain_ipv4addr(const char *ifname)

Obtain an IPv4 address via DHCP for the specified network interface. This function blocks until an address is obtained or an error occurs.

Parameters:

  • ifname – Network interface name (e.g., "eth0").

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_icmpv6_autoconfiguration(const char *ifname)

Perform IPv6 stateless address autoconfiguration (SLAAC) for the specified network interface.

Parameters:

  • ifname – Network interface name (e.g., "eth0").

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_obtain_ipv6addr(const char *ifname)

Obtain an IPv6 address via DHCPv6 for the specified network interface.

Parameters:

  • ifname – Network interface name (e.g., "eth0").

Returns:

0 on success; -1 on error with errno set appropriately.

DNS Server Address Management

int netlib_set_ipv4dnsaddr(const struct in_addr *inaddr)

Add an IPv4 DNS server address to the resolver configuration.

Parameters:

  • inaddr – Pointer to an in_addr structure containing the DNS server address.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_del_ipv4dnsaddr(const struct in_addr *inaddr)

Remove an IPv4 DNS server address from the resolver configuration.

Parameters:

  • inaddr – Pointer to an in_addr structure containing the DNS server address to remove.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_del_ipv4dnsaddr_by_index(int index)

Remove an IPv4 DNS server from the resolver configuration by index.

Parameters:

  • index – Index of the DNS server to remove (0-based).

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_set_ipv6dnsaddr(const struct in6_addr *inaddr)

Add an IPv6 DNS server address to the resolver configuration.

Parameters:

  • inaddr – Pointer to an in6_addr structure containing the DNS server address.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_del_ipv6dnsaddr(const struct in6_addr *inaddr)

Remove an IPv6 DNS server address from the resolver configuration.

Parameters:

  • inaddr – Pointer to an in6_addr structure containing the DNS server address to remove.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_del_ipv6dnsaddr_by_index(int index)

Remove an IPv6 DNS server from the resolver configuration by index.

Parameters:

  • index – Index of the DNS server to remove (0-based).

Returns:

0 on success; -1 on error with errno set appropriately.

Wireless Configuration

int netlib_getessid(const char *ifname, char *essid, size_t idlen)

Get the ESSID (network name) of a wireless network interface.

Parameters:

  • ifname – Wireless network interface name (e.g., "wlan0").

  • essid – Buffer to receive the ESSID string.

  • idlen – Size of the buffer.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_setessid(const char *ifname, const char *essid)

Set the ESSID (network name) for a wireless network interface.

Parameters:

  • ifname – Wireless network interface name (e.g., "wlan0").

  • essid – ESSID string to set.

Returns:

0 on success; -1 on error with errno set appropriately.

URL Parsing

int netlib_parsehttpurl(const char *url, uint16_t *port, char *hostname, int hostlen, char *filename, int namelen)

Parse an HTTP URL into its components.

Parameters:

  • url – URL string to parse (e.g., "http://example.com:8080/path/file").

  • port – Pointer to receive the port number (default 80 if not specified).

  • hostname – Buffer to receive the hostname.

  • hostlen – Size of the hostname buffer.

  • filename – Buffer to receive the path/filename.

  • namelen – Size of the filename buffer.

Returns:

0 on success; -1 on error.

int netlib_parseurl(const char *str, struct url_s *url)

Parse a generic URL into its components. This function handles various URL schemes beyond HTTP.

Parameters:

  • str – URL string to parse.

  • url – Pointer to a url_s structure to receive the parsed components.

Returns:

0 on success; -1 on error.

Server Support

int netlib_listenon(uint16_t portno)

Create a TCP socket and listen on the specified port. This is a convenience function for setting up a server socket.

Parameters:

  • portno – Port number to listen on.

Returns:

Socket descriptor on success; -1 on error with errno set appropriately.

void netlib_server(uint16_t portno, pthread_startroutine_t handler, int stacksize)

Create a simple server that listens on the specified port and spawns a new thread for each connection using the provided handler function.

Parameters:

  • portno – Port number to listen on.

  • handler – Function to call for each new connection. The handler receives the client socket descriptor as an argument.

  • stacksize – Stack size for handler threads.

Neighbor Table (IPv6)

ssize_t netlib_get_nbtable(struct neighbor_entry_s *nbtab, unsigned int nentries)

Retrieve the IPv6 neighbor table (similar to ARP for IPv4).

Parameters:

  • nbtab – Pointer to an array of neighbor_entry_s structures to receive the neighbor table entries.

  • nentries – Maximum number of entries in the array.

Returns:

Number of entries returned on success; -1 on error with errno set appropriately.

Connection Tracking (Netfilter)

int netlib_get_conntrack(sa_family_t family, netlib_conntrack_cb_t cb)

Retrieve connection tracking entries from the kernel’s connection tracking table.

Parameters:

  • family – Address family filter (AF_INET, AF_INET6, or AF_UNSPEC for all).

  • cb – Callback function to invoke for each connection. The callback receives a pointer to a netlib_conntrack_s structure.

Returns:

0 on success; -1 on error with errno set appropriately.

int netlib_parse_conntrack(const struct nlmsghdr *nlh, size_t len, struct netlib_conntrack_s *ct)

Parse a Netlink message containing connection tracking information.

Parameters:

  • nlh – Pointer to the Netlink message header.

  • len – Length of the message.

  • ct – Pointer to a netlib_conntrack_s structure to receive the parsed connection information.

Returns:

0 on success; -1 on error.