From 5dc38a88ad73807a7ae9b0c586116f1c8ebf10fc Mon Sep 17 00:00:00 2001 From: David Cermak Date: Tue, 17 Dec 2024 10:57:18 +0100 Subject: [PATCH] fix(sockutls): Explain declaration issues and suggestions --- components/sock_utils/README.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/components/sock_utils/README.md b/components/sock_utils/README.md index 750759476c..62a2157c22 100644 --- a/components/sock_utils/README.md +++ b/components/sock_utils/README.md @@ -6,13 +6,17 @@ This component provides simplified implementations of common socket-related util ## Supported Functions -| API | Description | Limitations | -|------------------|-------------------------------------------------------------|-------------------------------------------------------------------| -| `ifaddrs()` | Retrieves interface addresses using `esp_netif` | IPv4 addresses only | -| `socketpair()` | Creates a pair of connected sockets using `lwIP` loopback stream sockets | IPv4 sockets only | -| `pipe()` | Wraps `socketpair()` to provide unidirectional pipe-like functionality | Uses bidirectional sockets in place of true pipes | -| `getnameinfo()` | Converts IP addresses to human-readable form using `lwIP`'s `inet_ntop()` | IPv4 only; supports `NI_NUMERICHOST` and `NI_NUMERICSERV` flags only | -| `gai_strerror()` | Returns error code as a string | Simple numeric string representation only | -| `gethostname()` | Returns lwip netif hostname | Not a system-wide hostname, but interface specific hostname | +| API | Description | Limitations | Declared in | +|--------------------|-------------------------------------------------------------|-------------------------------------------------------------------|----------------------------------------| +| `ifaddrs()` | Retrieves interface addresses using `esp_netif` | IPv4 addresses only | `ifaddrs.h` | +| `socketpair()` *) | Creates a pair of connected sockets using `lwIP` loopback stream sockets | IPv4 sockets only | `socketpair.h`, `sys/socket.h` **) | +| `pipe()` *) | Wraps `socketpair()` to provide unidirectional pipe-like functionality | Uses bidirectional sockets in place of true pipes | `socketpair.h`, `unistd.h` ***) | +| `getnameinfo()` | Converts IP addresses to human-readable form using `lwIP`'s `inet_ntop()` | IPv4 only; supports `NI_NUMERICHOST` and `NI_NUMERICSERV` flags only | `getnameinfo.h`, `netdb.h` in ESP-IDF | +| `gai_strerror()` | Returns error code as a string | Simple numeric string representation only | `gai_strerror.h`, `netdb.h` **) | +| `gethostname()` | Returns lwip netif hostname | Not a system-wide hostname, but interface specific hostname | `gethostname.h`, `unistd.h` in ESP-IDF | -**Note**: `socketpair()` and `pipe()` are built on top of `lwIP` TCP sockets, inheriting the same characteristics. For instance, the maximum transmit buffer size is based on the `TCP_SND_BUF` setting. +**Notes**: + +- **`*)`** `socketpair()` and `pipe()` are built on top of `lwIP` TCP sockets, inheriting the same characteristics. For instance, the maximum transmit buffer size is based on the `TCP_SND_BUF` setting. +- **`**)`** `socketpair()` and `gai_strerror()` are declared in sock_utils header files, the declaration is propagated to ESP-IDF from v5.5 to the official header files. If you're using older IDF version, you need to manually pre-include related header files from the sock_utils public include directory. +- **`***)`** `pipe()` is declared in compiler's `sys/unistd.h`.