NAME

       libwget-net - TCP sockets

SYNOPSIS

   Functions
       int wget_net_init (void)
       int wget_net_deinit (void)
       struct addrinfo * wget_tcp_resolve (wget_tcp_t *tcp, const char *host, uint16_t port)
       void wget_tcp_set_tcp_fastopen (wget_tcp_t G_GNUC_WGET_UNUSED *tcp, int G_GNUC_WGET_UNUSED
           tcp_fastopen)
       char wget_tcp_get_tcp_fastopen (wget_tcp_t *tcp)
       void wget_tcp_set_tls_false_start (wget_tcp_t *tcp, int false_start)
       char wget_tcp_get_tls_false_start (wget_tcp_t *tcp)
       void wget_tcp_set_dns_caching (wget_tcp_t *tcp, int caching)
       int wget_tcp_get_dns_caching (wget_tcp_t *tcp)
       void wget_tcp_set_protocol (wget_tcp_t *tcp, int protocol)
       int wget_tcp_get_protocol (wget_tcp_t *tcp)
       void wget_tcp_set_preferred_family (wget_tcp_t *tcp, int family)
       int wget_tcp_get_preferred_family (wget_tcp_t *tcp)
       void wget_tcp_set_family (wget_tcp_t *tcp, int family)
       int wget_tcp_get_family (wget_tcp_t *tcp)
       int wget_tcp_get_local_port (wget_tcp_t *tcp)
       void wget_tcp_set_stats_dns (wget_stats_callback_t fn)
       const void * wget_tcp_get_stats_dns (const wget_dns_stats_t type, const void *_stats)
       void wget_tcp_set_dns_timeout (wget_tcp_t *tcp, int timeout)
       void wget_tcp_set_connect_timeout (wget_tcp_t *tcp, int timeout)
       void wget_tcp_set_timeout (wget_tcp_t *tcp, int timeout)
       int wget_tcp_get_timeout (wget_tcp_t *tcp)
       void wget_tcp_set_bind_address (wget_tcp_t *tcp, const char *bind_address)
       void wget_tcp_set_ssl (wget_tcp_t *tcp, int ssl)
       int wget_tcp_get_ssl (wget_tcp_t *tcp)
       void wget_tcp_set_ssl_hostname (wget_tcp_t *tcp, const char *hostname)
       const char * wget_tcp_get_ssl_hostname (wget_tcp_t *tcp)
       wget_tcp_t * wget_tcp_init (void)
       void wget_tcp_deinit (wget_tcp_t **_tcp)
       int wget_tcp_ready_2_transfer (wget_tcp_t *tcp, int flags)
       int wget_tcp_connect (wget_tcp_t *tcp, const char *host, uint16_t port)
       int wget_tcp_tls_start (wget_tcp_t *tcp)
       void wget_tcp_tls_stop (wget_tcp_t *tcp)
       ssize_t wget_tcp_read (wget_tcp_t *tcp, char *buf, size_t count)
       ssize_t wget_tcp_write (wget_tcp_t *tcp, const char *buf, size_t count)
       ssize_t wget_tcp_vprintf (wget_tcp_t *tcp, const char *fmt, va_list args)
       ssize_t wget_tcp_printf (wget_tcp_t *tcp, const char *fmt,...)
       void wget_tcp_close (wget_tcp_t *tcp)

Detailed Description

       TCP sockets and DNS cache management functions.

       The following features are supported:

       • TCP Fast Open (RFC 7413)

       • SSL/TLS

       • DNS caching

       Most functions here take a wget_tcp_t structure as argument.

       The wget_tcp_t 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.

       • Caching: whether to use DNS caching or not. The DNS cache is kept internally and is
         shared among all connections. You can disable it for a specific wget_tcp_t, so that
         specific connection will not use the DNS cache, or you can disable it globally.

       • 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_t 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

       • DNS caching: yes

       • 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().

   struct addrinfo* wget_tcp_resolve (wget_tcp_t * tcp, const char * host, uint16_t port)
       Parameters
           tcp A wget_tcp_t structure, obtained with a previous call to wget_tcp_init().
           host Hostname
           port TCP destination port

       Returns
           A struct addrinfo structure (defined in libc's <netdb.h>). Must be freed by the caller
           with freeaddrinfo(3).

       Resolve a host name into its IPv4/IPv6 address.

       The caching parameter tells wget_tcp_resolve() to use the DNS cache as long as possible.
       This means that if the queried hostname is found in the cache, that will be returned
       without querying any actual DNS server. If no such entry is found, a DNS query is
       performed, and the result stored in the cache. You can enable caching with
       wget_tcp_set_dns_caching().

       Note that if caching is false, the DNS cache will not be used at all. Not only it won't be
       used for looking up the hostname, but the addresses returned by the DNS server will not be
       stored in it either.

       This function uses the following wget_tcp_t parameters:

       • DNS caching: Use the internal DNS cache. If the hostname is found there, return it
         immediately. Otherwise continue and do a normal DNS query, and store the result in the
         cache. You can enable this with wget_tcp_set_dns_cache().

       • Address family: Desired address family for the returned addresses. This will typically
         be AF_INET or AF_INET6, but it can be any of the values defined in <socket.h>.
         Additionally, AF_UNSPEC means you don't care: it will return any address family that can
         be used with the specified host and port. If family is different than AF_UNSPEC and the
         specified family is not found, that's an error condition and thus wget_tcp_resolve()
         will return NULL. You can set this with wget_tcp_set_family().

       • Preferred address family: Tries to resolve addresses of this family if possible. This is
         only honored if family (see point above) is AF_UNSPEC.

       The parameter tcp might be NULL. In that case, the aforementioned behavior is governed by
       global options: those set by previous calls to wget_tcp_set_dns_caching(),
       wget_tcp_set_family() and wget_tcp_set_preferred_family(), etc.

       The returned addrinfo structure must be freed with freeaddrinfo(3). Note that if you call
       wget_tcp_connect(), this will be done for you when you call wget_tcp_close(). But if you
       call this function alone, you must take care of it.

   void wget_tcp_set_tcp_fastopen (wget_tcp_t G_GNUC_WGET_UNUSED * tcp, int G_GNUC_WGET_UNUSED
       tcp_fastopen)
       Parameters
           tcp A wget_tcp_t 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.

   char wget_tcp_get_tcp_fastopen (wget_tcp_t * tcp)
       Parameters
           tcp A wget_tcp_t 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_t * tcp, int false_start)
       Parameters
           tcp A wget_tcp_t 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.

   char wget_tcp_get_tls_false_start (wget_tcp_t * tcp)
       Parameters
           tcp A wget_tcp_t 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_dns_caching (wget_tcp_t * tcp, int caching)
       Parameters
           tcp A wget_tcp_t structure representing a TCP connection, returned by wget_tcp_init().
           Might be NULL.
           caching 1 or 0, whether to enable or disable DNS caching

       Enable or disable DNS caching for the connection provided, or globally.

       The DNS cache is kept internally in memory, and is used in wget_tcp_resolve() to speed up
       DNS queries.

       If tcp is NULL, DNS caching is enabled or disabled globally.

   int wget_tcp_get_dns_caching (wget_tcp_t * tcp)
       Parameters
           tcp A wget_tcp_t structure representing a TCP connection, returned by wget_tcp_init().
           Might be NULL.

       Returns
           1 if DNS caching is enabled, 0 otherwise.

       Tells whether DNS caching is enabled or not.

       You can enable and disable it with wget_tcp_set_dns_caching().

   void wget_tcp_set_protocol (wget_tcp_t * tcp, int protocol)
       Parameters
           tcp A wget_tcp_t 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_t * tcp)
       Parameters
           tcp A wget_tcp_t 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_t * tcp, int family)
       Parameters
           tcp A wget_tcp_t structure representing a TCP connection, returned by wget_tcp_init().
           Might be NULL.
           family One of the socket families defined in <socket.h>, 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_t * tcp)
       Parameters
           tcp A wget_tcp_t structure representing a TCP connection, returned by wget_tcp_init().
           Might be NULL.

       Returns
           One of the socket families defined in <socket.h>, 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_t * tcp, int family)
       Parameters
           tcp A wget_tcp_t structure representing a TCP connection, returned by wget_tcp_init().
           Might be NULL.
           family One of the socket families defined in <socket.h>, 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_t * tcp)
       Parameters
           tcp A wget_tcp_t structure representing a TCP connection, returned by wget_tcp_init().
           Might be NULL.

       Returns
           One of the socket families defined in <socket.h>, 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_t * tcp)
       Parameters
           tcp A wget_tcp_t 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_stats_dns (wget_stats_callback_t fn)
       Parameters
           fn A wget_stats_callback_t callback function used to collect DNS statistics

       Set callback function to be called once DNS statistics for a host are collected

   const void* wget_tcp_get_stats_dns (const wget_dns_stats_t type, const void * _stats)
       Parameters
           type A wget_dns_stats_t constant representing DNS statistical info to return
           _stats An internal pointer sent to callback function

       Returns
           DNS statistical info in question

       Get the specific DNS statistics information

   void wget_tcp_set_dns_timeout (wget_tcp_t * tcp, int timeout)
       Parameters
           tcp A TCP connection.
           timeout The timeout value.

       Set the timeout (in milliseconds) for the DNS queries.

       This is the maximum time to wait until we get a response from the server.

       The following two values are special:

       • 0: No timeout, immediate.

       • -1: Infinite timeout. Wait indefinitely.

   void wget_tcp_set_connect_timeout (wget_tcp_t * 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_t * 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_t * 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_t * 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_ssl (wget_tcp_t * tcp, int ssl)
       Parameters
           tcp A wget_tcp_t 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.

   int wget_tcp_get_ssl (wget_tcp_t * tcp)
       Parameters
           tcp A wget_tcp_t 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.

   void wget_tcp_set_ssl_hostname (wget_tcp_t * tcp, const char * hostname)
       Parameters
           tcp A wget_tcp_t 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_t * tcp)
       Parameters
           tcp A wget_tcp_t 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_t* wget_tcp_init (void)
       Returns
           A new wget_tcp_t structure, with pre-defined parameters.

       Create a new wget_tcp_t 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_t ** _tcp)
       Parameters
           _tcp A pointer to a wget_tcp_t 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_t 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 re-use it. Call
       wget_dns_cache_free() if you want to free it.

   int wget_tcp_ready_2_transfer (wget_tcp_t * 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_t * tcp, const char * host, uint16_t port)
       Parameters
           tcp A wget_tcp_t 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_t. 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.

       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_t * 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_t * 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_t * 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_t * 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_t * 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_t * 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_t * tcp)
       Parameters
           tcp An active TCP connection

       Close a TCP connection.

Author

       Generated automatically by Doxygen for wget2 from the source code.