--- name: "libwget-net" section: "3" platform: "linux" package: "wget2-dev" version: "2.2.0+ds-1+deb13u1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/libwget-net" --- # libwget-net(3) TCP sockets ## NAME libwget-net - TCP sockets ## SYNOPSIS ### Functions int **wget\_net\_init** (void)\ int **wget\_net\_deinit** (void)\ void **wget\_tcp\_set\_dns** (wget\_tcp \*tcp, **wget\_dns** \*dns)\ void **wget\_tcp\_set\_tcp\_fastopen** (wget\_tcp \*tcp, bool tcp\_fastopen)\ bool **wget\_tcp\_get\_tcp\_fastopen** (wget\_tcp \*tcp)\ void **wget\_tcp\_set\_tls\_false\_start** (wget\_tcp \*tcp, bool false\_start)\ bool **wget\_tcp\_get\_tls\_false\_start** (wget\_tcp \*tcp)\ void **wget\_tcp\_set\_protocol** (wget\_tcp \*tcp, int protocol)\ int **wget\_tcp\_get\_protocol** (wget\_tcp \*tcp)\ void **wget\_tcp\_set\_preferred\_family** (wget\_tcp \*tcp, int family)\ int **wget\_tcp\_get\_preferred\_family** (wget\_tcp \*tcp)\ void **wget\_tcp\_set\_family** (wget\_tcp \*tcp, int family)\ int **wget\_tcp\_get\_family** (wget\_tcp \*tcp)\ int **wget\_tcp\_get\_local\_port** (wget\_tcp \*tcp)\ void **wget\_tcp\_set\_connect\_timeout** (wget\_tcp \*tcp, int timeout)\ void **wget\_tcp\_set\_timeout** (wget\_tcp \*tcp, int timeout)\ int **wget\_tcp\_get\_timeout** (wget\_tcp \*tcp)\ void **wget\_tcp\_set\_bind\_address** (wget\_tcp \*tcp, const char \*bind\_address)\ void **wget\_tcp\_set\_bind\_interface** (wget\_tcp \*tcp, const char \*bind\_interface)\ void **wget\_tcp\_set\_ssl** (wget\_tcp \*tcp, bool ssl)\ bool **wget\_tcp\_get\_ssl** (wget\_tcp \*tcp)\ const char \* **wget\_tcp\_get\_ip** (wget\_tcp \*tcp)\ void **wget\_tcp\_set\_ssl\_hostname** (wget\_tcp \*tcp, const char \*hostname)\ const char \* **wget\_tcp\_get\_ssl\_hostname** (wget\_tcp \*tcp)\ wget\_tcp \* **wget\_tcp\_init** (void)\ void **wget\_tcp\_deinit** (wget\_tcp \*\*\_tcp)\ int **wget\_tcp\_ready\_2\_transfer** (wget\_tcp \*tcp, int flags)\ int **wget\_tcp\_connect** (wget\_tcp \*tcp, const char \*host, uint16\_t port)\ int **wget\_tcp\_tls\_start** (wget\_tcp \*tcp)\ void **wget\_tcp\_tls\_stop** (wget\_tcp \*tcp)\ ssize\_t **wget\_tcp\_read** (wget\_tcp \*tcp, char \*buf, size\_t count)\ ssize\_t **wget\_tcp\_write** (wget\_tcp \*tcp, const char \*buf, size\_t count)\ ssize\_t **wget\_tcp\_vprintf** (wget\_tcp \*tcp, const char \*fmt, va\_list args)\ ssize\_t **wget\_tcp\_printf** (wget\_tcp \*tcp, const char \*fmt,...)\ void **wget\_tcp\_close** (wget\_tcp \*tcp)\ ## Detailed Description TCP sockets and DNS cache management functions. The following features are supported: - • TCP Fast Open (`RFC 7413`) - • SSL/TLS Most functions here take a `wget_tcp` structure as argument. The `wget_tcp` structure represents a TCP connection. You create it with **wget\_tcp\_init()** and destroy it with **wget\_tcp\_deinit()**. You can connect to a remote host with **wget\_tcp\_connect()**, or listen for incoming connections (and accept them) with wget\_tcp\_listen() and wget\_tcp\_accept(). You end a connection with **wget\_tcp\_close()**. There are several knobs you can use to customize the behavior of most functions here. The list that follows describes the most important parameters, although you can look at the getter and setter functions here to see them all (`wget_tcp_get_xxx`, `wget_tcp_set_xxx`). - • Timeout: maximum time to wait for an operation to complete. For example, for **wget\_tcp\_read()**, it sets the maximum time to wait until some data is available to read. Most functions here can be non-blocking (with timeout = 0) returning immediately or they can block indefinitely until something happens (with timeout = -1). For any value greater than zero, the timeout is taken as milliseconds. - • Family and preferred family: these are used to determine which address family should be used when resolving a host name or IP address. You probably use `AF_INET` or `AF_INET6` most of the time. The first one forces the library to use that family, failing if it cannot find any IP address with it. The second one is just a hint, about which family you would prefer; it will try to get an address of that family if possible, and will get another one if not. - • SSL/TLS: do you want to use TLS? When you create a new `wget_tcp` with **wget\_tcp\_init()**, it is initialized with the following parameters: - • Timeout: -1 - • Connection timeout (max. time to wait for a connection to be accepted by the remote host): -1 - • DNS timeout (max. time to wait for a DNS query to return): -1 - • Family: `AF_UNSPEC` (basically means 'I don't care, pick the first one available'). ## Function Documentation ### int wget\_net\_init (void) **Returns** 0 for success, else failure Initialize the resources needed for network operations. ### int wget\_net\_deinit (void) **Returns** 0 for success, else failure Free the resources allocated by **wget\_net\_init()**. ### void wget\_tcp\_set\_dns (wget\_tcp \* tcp, wget\_dns \* dns) **Parameters** *tcp* A `wget_tcp` structure representing a TCP connection, returned by **wget\_tcp\_init()**. \ *protocol* The protocol, either WGET\_PROTOCOL\_HTTP\_2\_0 or WGET\_PROTOCOL\_HTTP\_1\_1. Set the protocol for the connection provided, or globally. If `tcp` is NULL, theprotocol will be set globally (for all connections). Otherwise, only for the provided connection (`tcp`). ### void wget\_tcp\_set\_tcp\_fastopen (wget\_tcp \* tcp, bool tcp\_fastopen) **Parameters** *tcp* A `wget_tcp` structure representing a TCP connection, returned by **wget\_tcp\_init()**. Might be NULL. \ *tcp\_fastopen* 1 or 0, whether to enable or disable TCP Fast Open. Enable or disable TCP Fast Open (`RFC 7413`), if available. This function is a no-op on systems where TCP Fast Open is not supported. If `tcp` is NULL, TCP Fast Open is enabled or disabled globally. ### bool wget\_tcp\_get\_tcp\_fastopen (wget\_tcp \* tcp) **Parameters** *tcp* A `wget_tcp` structure representing a TCP connection, returned by **wget\_tcp\_init()**. Might be NULL. **Returns** 1 if TCP Fast Open is enabled, 0 otherwise. Tells whether TCP Fast Open is enabled or not. You can enable and disable it with **wget\_tcp\_set\_tcp\_fastopen()**. ### void wget\_tcp\_set\_tls\_false\_start (wget\_tcp \* tcp, bool false\_start) **Parameters** *tcp* A `wget_tcp` structure representing a TCP connection, returned by **wget\_tcp\_init()**. Might be NULL. \ *false\_start* 1 or 0, whether to enable or disable TLS False Start. Enable or disable TLS False Start (`RFC 7918`). If `tcp` is NULL, TLS False Start is enabled or disabled globally. ### bool wget\_tcp\_get\_tls\_false\_start (wget\_tcp \* tcp) **Parameters** *tcp* A `wget_tcp` structure representing a TCP connection, returned by **wget\_tcp\_init()**. Might be NULL. **Returns** 1 if TLS False Start is enabled, 0 otherwise. Tells whether TLS False Start is enabled or not. You can enable and disable it with **wget\_tcp\_set\_tls\_false\_start()**. ### void wget\_tcp\_set\_protocol (wget\_tcp \* tcp, int protocol) **Parameters** *tcp* A `wget_tcp` structure representing a TCP connection, returned by **wget\_tcp\_init()**. \ *protocol* The protocol, either WGET\_PROTOCOL\_HTTP\_2\_0 or WGET\_PROTOCOL\_HTTP\_1\_1. Set the protocol for the connection provided, or globally. If `tcp` is NULL, theprotocol will be set globally (for all connections). Otherwise, only for the provided connection (`tcp`). ### int wget\_tcp\_get\_protocol (wget\_tcp \* tcp) **Parameters** *tcp* A `wget_tcp` structure representing a TCP connection, returned by **wget\_tcp\_init()**. **Returns** The protocol with this connection, currently WGET\_PROTOCOL\_HTTP\_2\_0 or WGET\_PROTOCOL\_HTTP\_1\_1. Get protocol used with the provided connection, or globally (if `tcp` is NULL). ### void wget\_tcp\_set\_preferred\_family (wget\_tcp \* tcp, int family) **Parameters** *tcp* A `wget_tcp` structure representing a TCP connection, returned by **wget\_tcp\_init()**. Might be NULL. \ *family* One of the socket families defined in ``, such as `AF_INET` or `AF_INET6`. Tells the preferred address family that should be used when establishing a TCP connection. wget\_tcp\_resolve() will favor that and pick an address of that family if possible. If `tcp` is NULL, the preferred address family will be set globally. ### int wget\_tcp\_get\_preferred\_family (wget\_tcp \* tcp) **Parameters** *tcp* A `wget_tcp` structure representing a TCP connection, returned by **wget\_tcp\_init()**. Might be NULL. **Returns** One of the socket families defined in ``, such as `AF_INET` or `AF_INET6`. Get the preferred address family that was previously set with **wget\_tcp\_set\_preferred\_family()**. ### void wget\_tcp\_set\_family (wget\_tcp \* tcp, int family) **Parameters** *tcp* A `wget_tcp` structure representing a TCP connection, returned by **wget\_tcp\_init()**. Might be NULL. \ *family* One of the socket families defined in ``, such as `AF_INET` or `AF_INET6`. Tell the address family that will be used when establishing a TCP connection. wget\_tcp\_resolve() will pick an address of that family, or fail if it cannot find one. If `tcp` is NULL, the address family will be set globally. ### int wget\_tcp\_get\_family (wget\_tcp \* tcp) **Parameters** *tcp* A `wget_tcp` structure representing a TCP connection, returned by **wget\_tcp\_init()**. Might be NULL. **Returns** One of the socket families defined in ``, such as `AF_INET` or `AF_INET6`. Get the address family that was previously set with **wget\_tcp\_set\_family()**. ### int wget\_tcp\_get\_local\_port (wget\_tcp \* tcp) **Parameters** *tcp* A `wget_tcp` structure representing a TCP connection, returned by **wget\_tcp\_init()**. Might be NULL. **Returns** The local port. Get the port number the TCP connection `tcp` is bound to on the local machine. ### void wget\_tcp\_set\_connect\_timeout (wget\_tcp \* tcp, int timeout) **Parameters** *tcp* A TCP connection. \ *timeout* The timeout value. Set the timeout for the TCP connection. This is the maximum time to wait until the remote host accepts our connection. The following two values are special: - • `0`: No timeout, immediate. - • `-1`: Infinite timeout. Wait indefinitely. ### void wget\_tcp\_set\_timeout (wget\_tcp \* tcp, int timeout) **Parameters** *tcp* A TCP connection. \ *timeout* The timeout value. Set the timeout (in milliseconds) for **wget\_tcp\_read()**, **wget\_tcp\_write()** and wget\_tcp\_accept(). The following two values are special: - • `0`: No timeout, immediate. - • `-1`: Infinite timeout. Wait indefinitely. ### int wget\_tcp\_get\_timeout (wget\_tcp \* tcp) **Parameters** *tcp* A TCP connection. **Returns** The timeout value that was set with **wget\_tcp\_set\_timeout()**. Get the timeout value that was set with **wget\_tcp\_set\_timeout()**. ### void wget\_tcp\_set\_bind\_address (wget\_tcp \* tcp, const char \* bind\_address) **Parameters** *tcp* A TCP connection. Might be NULL. \ *bind\_address* An IP address or host name. Set the IP address/hostname the socket `tcp` will bind to on the local machine when connecting to a remote host. The hostname can explicitly set the port after a colon (':'). This is mainly relevant to **wget\_tcp\_connect()**. ### void wget\_tcp\_set\_bind\_interface (wget\_tcp \* tcp, const char \* bind\_interface) **Parameters** *tcp* A TCP connection. Might be NULL. \ *bind\_interface* A network interface name. Set the Network Interface the socket `tcp` will bind to on the local machine when connecting to a remote host. This is mainly relevant to **wget\_tcp\_connect()**. ### void wget\_tcp\_set\_ssl (wget\_tcp \* tcp, bool ssl) **Parameters** *tcp* A `wget_tcp` structure representing a TCP connection, returned by **wget\_tcp\_init()**. \ *ssl* Flag to enable or disable SSL/TLS on the given connection. Enable or disable SSL/TLS. If `tcp` is NULL, TLS will be enabled globally. Otherwise, TLS will be enabled only for the provided connection. ### bool wget\_tcp\_get\_ssl (wget\_tcp \* tcp) **Parameters** *tcp* A `wget_tcp` structure representing a TCP connection, returned by **wget\_tcp\_init()**. **Returns** 1 if TLs is enabled, 0 otherwise. Tells whether TLS is enabled or not. ### const char \* wget\_tcp\_get\_ip (wget\_tcp \* tcp) **Parameters** *tcp* A `wget_tcp` structure representing a TCP connection, returned by **wget\_tcp\_init()**. **Returns** IP address as string, NULL if not available. Returns the IP address of a `wget_tcp` instance. ### void wget\_tcp\_set\_ssl\_hostname (wget\_tcp \* tcp, const char \* hostname) **Parameters** *tcp* A `wget_tcp` structure representing a TCP connection, returned by **wget\_tcp\_init()**. Might be NULL. \ *hostname* A hostname. The value of the SNI field. Sets the TLS Server Name Indication (SNI). For more info see `RFC 6066, sect. 3`. SNI basically does at the TLS layer what the `Host:` header field does at the application (HTTP) layer. The server might use this information to locate an appropriate X.509 certificate from a pool of certificates, or to direct the request to a specific virtual host, for instance. ### const char \* wget\_tcp\_get\_ssl\_hostname (wget\_tcp \* tcp) **Parameters** *tcp* A `wget_tcp` structure representing a TCP connection, returned by **wget\_tcp\_init()**. Might be NULL. **Returns** A hostname. The value of the SNI field. Returns the value that was set to SNI with a previous call to **wget\_tcp\_set\_ssl\_hostname()**. ### wget\_tcp \* wget\_tcp\_init (void) **Returns** A new `wget_tcp` structure, with pre-defined parameters. Create a new `wget_tcp` structure, that represents a TCP connection. It can be destroyed with **wget\_tcp\_deinit()**. This function does not establish or modify a TCP connection in any way. That can be done with the other functions in this file, such as **wget\_tcp\_connect()** or wget\_tcp\_listen() and wget\_tcp\_accept(). ### void wget\_tcp\_deinit (wget\_tcp \*\* \_tcp) **Parameters** *\_tcp* A **pointer** to a `wget_tcp` structure representing a TCP connection, returned by **wget\_tcp\_init()**. Might be NULL. Release a TCP connection (created with **wget\_tcp\_init()**). The `wget_tcp` structure will be freed and `_tcp` will be set to NULL. If `_tcp` is NULL, the SNI field will be cleared. Does not free the internal DNS cache, so that other connections can reuse it. Call **wget\_dns\_cache\_free()** if you want to free it. ### int wget\_tcp\_ready\_2\_transfer (wget\_tcp \* tcp, int flags) Test whether the given connection (`tcp`) is ready to read or write. The parameter `flags` can have one or both (with bitwise OR) of the following values: - • `WGET_IO_READABLE`: Is data available for reading? - • `WGET_IO_WRITABLE`: Can we write immediately (without having to wait until the TCP buffer frees)? ### int wget\_tcp\_connect (wget\_tcp \* tcp, const char \* host, uint16\_t port) **Parameters** *tcp* A `wget_tcp` structure representing a TCP connection, returned by **wget\_tcp\_init()**. \ *host* Hostname or IP address to connect to. \ *port* port number **Returns** WGET\_E\_SUCCESS (0) on success, or a negative integer on error (some of WGET\_E\_XXX defined in `<`**wget.h**`>`**).** **Open a TCP connection with a remote host.** **This function will use TLS if it has been enabled for this** `wget_tcp`**. You can enable it with wget\_tcp\_set\_ssl(). Additionally, you can also use wget\_tcp\_set\_ssl\_hostname() to set the Server Name Indication (SNI).** **You can set which IP address and port on the local machine will the socket be bound to with wget\_tcp\_set\_bind\_address(). Otherwise the socket will bind to any address and port chosen by the operating system.** **You can also set which Network Interface on the local machine will the socket be bound to with wget\_tcp\_bind\_interface().** **This function will try to use TCP Fast Open if enabled and available. If TCP Fast Open fails, it will fall back to the normal TCP handshake, without raising an error. You can enable TCP Fast Open with wget\_tcp\_set\_tcp\_fastopen().** **If the connection fails,** `WGET_E_CONNECT` **is returned.** ### int wget\_tcp\_tls\_start (wget\_tcp \* tcp) **Parameters** *tcp* **An active connection.** **Returns** **WGET\_E\_SUCCESS (0) on success, or a negative integer on error (one of WGET\_E\_XXX, defined in** `<`**wget.h**`>`**). Start TLS for this connection.** **This will typically be called by wget\_tcp\_accept().** **If the socket is listening (e.g. wget\_tcp\_listen(), wget\_tcp\_accept()), it will expect the client to perform a TLS handshake, and fail if it doesn't.** **If this is a client connection (e.g. wget\_tcp\_connect()), it will try perform a TLS handshake with the server.** ### void wget\_tcp\_tls\_stop (wget\_tcp \* tcp) **Parameters** *tcp* **An active connection.** **Stops TLS, but does not close the connection. Data will be transmitted in the clear from now on.** ### ssize\_t wget\_tcp\_read (wget\_tcp \* tcp, char \* buf, size\_t count) **Parameters** *tcp* **An active TCP connection.** \ *buf* **Destination buffer, at least** `count` **bytes long.** \ *count* **Length of the buffer** `buf`**.** **Returns** **Number of bytes read** **Read** `count` **bytes of data from the TCP connection represented by** `tcp` **and store them in the buffer** `buf`**.** **This function knows whether the provided connection is over TLS or not and it will do the right thing.** **The** `tcp->timeout` **parameter is taken into account by this function as well. It specifies how long should this function wait until there's data available to read (in milliseconds). The default timeout is -1, which means to wait indefinitely.** **The following two values are special:** - • `0`**: No timeout, immediate.** - • `-1`**: Infinite timeout. Wait indefinitely until a new connection comes.** **You can set the timeout with wget\_tcp\_set\_timeout().** **In particular, the returned value will be zero if no data was available for reading before the timeout elapsed.** ### ssize\_t wget\_tcp\_write (wget\_tcp \* tcp, const char \* buf, size\_t count) **Parameters** *tcp* **An active TCP connection.** \ *buf* **A buffer, at least** `count` **bytes long.** \ *count* **Number of bytes from** `buf` **to send through** `tcp`**.** **Returns** **The number of bytes written, or -1 on error.** **Write** `count` **bytes of data from the buffer** `buf` **to the TCP connection represented by** `tcp`**.** **This function knows whether the provided connection is over TLS or not and it will do the right thing.** **TCP Fast Open will be used if it's available and enabled. You can enable TCP Fast Open with wget\_tcp\_set\_tcp\_fastopen().** **This function honors the** `timeout` **parameter. If the write operation fails because the socket buffer is full, then it will wait at most that amount of milliseconds. If after the timeout the socket is still unavailable for writing, this function returns zero.** **The following two values are special:** - • `0`**: No timeout. The socket must be available immediately.** - • `-1`**: Infinite timeout. Wait indefinitely until the socket becomes available.** **You can set the timeout with wget\_tcp\_set\_timeout().** ### ssize\_t wget\_tcp\_vprintf (wget\_tcp \* tcp, const char \* fmt, va\_list args) **Parameters** *tcp* **An active TCP connection.** \ *fmt* **Format string (like in** `printf(3)`**).** \ *args* `va_args` **argument list (like in** `vprintf(3)`**)** **Write data in vprintf-style format, to the connection** `tcp`**.** **It uses wget\_tcp\_write().** ### ssize\_t wget\_tcp\_printf (wget\_tcp \* tcp, const char \* fmt, ...) **Parameters** *tcp* **An active TCP connection.** \ *fmt* **Format string (like in** `printf(3)`**).** **Write data in printf-style format, to the connection** `tcp`**.** **It uses wget\_tcp\_vprintf(), which in turn uses wget\_tcp\_write().** ### void wget\_tcp\_close (wget\_tcp \* tcp) **Parameters** *tcp* **An active TCP connection** **Close a TCP connection.** ## Author **Generated automatically by Doxygen for wget2 from the source code.**