libgslutil  1.2.3
Macros | Enumerations | Functions
IP networking

Macros

#define GSL_IPV6ONLY   (0x00000001)
 Force IPv6 sockets to bind to only IPv6 addresses.This flag causes IPv6 server sockets to bind only to IPv6 addresses, not to IPv4-mapped addresses. Useful when you are binding to multiple wildcard addresses. More...
 

Enumerations

enum  ip_subproto_t { ip_subproto_any, ip_subproto_tcp, ip_subproto_udp }
 IP-oriented connections: sub-protocol. More...
 

Functions

int ip_connect (int flags, const struct addrinfo *addr))
 Connect to a remote IP server. More...
 
int ip_server (int flags, const struct addrinfo *addr))
 Create an IP server. More...
 
int ip_accept (int flags, int fd, struct addrinfo *addr))
 Accept a client from a connection-oriented IP server. More...
 
int * ip_servers2 (int flags, const struct addrinfo *addrs)
 Create a set of IP servers (advanced interface). More...
 
int * ip_servers (int flags, enum ip_subproto_t subproto, const char *addrs)
 Create a set of IP servers (basic interface). More...
 

Detailed Description

ip_connect() instantiates and connects a client socket. ip_server() instantiates and binds a server socket. ip_accept() accepts incoming connections on a server socket.

Macro Definition Documentation

◆ GSL_IPV6ONLY

#define GSL_IPV6ONLY   (0x00000001)

Force IPv6 sockets to bind to only IPv6 addresses.This flag causes IPv6 server sockets to bind only to IPv6 addresses, not to IPv4-mapped addresses. Useful when you are binding to multiple wildcard addresses.

Enumeration Type Documentation

◆ ip_subproto_t

IP-oriented connections: sub-protocol.

This contains the list of protocols that we know about over the IPv4 and IPv6 layers.

Enumerator
ip_subproto_any 

Any type acceptable.

ip_subproto_tcp 

TCP (transmission control protocol)

ip_subproto_udp 

UDP (user datagram protocol)

Function Documentation

◆ ip_connect()

int ip_connect ( int  flags,
const struct addrinfo *  addr 
)

Connect to a remote IP server.

Parameters
flagsFlags for connection.
addrAddress of remote host (perhaps from ip_resolve()).
Return values
-1on error (and see errno).
Returns
file descriptor of new client on success.

This function attempts to create an IP client and connect it to a remote server. It will return -1 on error (errno will be set according to socket() or connect()).

flags may contain GSL_NONBLOCK to specify non-blocking mode.

If addr contains more than one entry, each entry will be tried in turn to connect to the host until one succeeds. In this case, -1 will be returned if none of the addresses succeed.

◆ ip_server()

int ip_server ( int  flags,
const struct addrinfo *  addr 
)

Create an IP server.

Parameters
flagsFlags for server socket.
addrAddress to bind to.
Return values
-1on error (and see errno).
Returns
file descriptor of new server on success.

This function attempts to create an IP server and bind it to the specified local address. It will return -1 on error (errno will be set according to socket(), bind() or (if relevant) listen()). The address will typically come from ip_resolve(), which can be called with a host argument of 0 to return an address that allows the server to listen on all network interfaces.

flags may contain GSL_NONBLOCK to specify non-blocking mode (this will only affect the server; newly-accepted clients may be either blocking or non-blocking). It may also contain GSL_IPV6ONLY to ensure a socket is not bound to an IPv4-in-IPv6 mapped address (ignored unless addr is an IPv6 address).

See also
ip_accept().

◆ ip_accept()

int ip_accept ( int  flags,
int  fd,
struct addrinfo *  addr 
)

Accept a client from a connection-oriented IP server.

Parameters
flagsFlags for client socket.
fdServer's file descriptor.
[out]addrThe client's remote address. May be 0.
Return values
-1on error (and see errno).
Returns
file descriptor of new client on success.

This function attempts to accept() a connection from an IP server. It will retry on any error except EAGAIN, which indicates that there are actually no more clients to accept. It should be called in a loop until it does this. If a persistent error occurs, -1 will be returned and the last error recorded in errno.

The client's remote address may be retrieved by passing a pointer to a struct addrinfo in addr (see sockaddr_to_addrinfo()).

flags may contain GSL_NONBLOCK to specify that a newly-accepted client will be in non-blocking mode.

◆ ip_servers2()

int* ip_servers2 ( int  flags,
const struct addrinfo *  addrs 
)

Create a set of IP servers (advanced interface).

Parameters
flagsFlags for server socket.
addrsAddress(es) to bind to, in linked list form as per ipaddr_resolve or getaddrinfo(3).
Returns
Pointer to newly-allocated -1-terminated array of file descriptors.
Return values
0on error (and see errno).

This function creates a set of IP server sockets based on all the addresses given in the list addrs.

Any IPv6 sockets created are bound with IPV6_V6ONLY (see ipv6(7)) in order to avoid problems with "Address already in use" when binding to e.g. the wildcard address.

If resolving or binding of any of the addresses fails, then any opened sockets are closed and 0 is returned. errno will be set appropriately.

The returned array should be freed with free(3). The array has a terminating value of -1, the invalid file descriptor.

◆ ip_servers()

int* ip_servers ( int  flags,
enum ip_subproto_t  subproto,
const char *  addrs 
)

Create a set of IP servers (basic interface).

Parameters
flagsFlags for server socket.
subprotoIP subprotocol (TCP, UDP, any).
addrsAddress(es) to bind to.
Returns
Pointer to newly-allocated -1-terminated array of file descriptors.
Return values
0on error (and see errno).

This function creates a set of IP server sockets based on all the addresses given in the string addrs.

If subproto is specified as TCP or UDP, then only TCP or UDP sockets (respectively) will be created. However, if subproto is specified as ip_subproto_any, then both TCP and UDP sockets may be created, depending on how the service name is specified. A service name specified as a port number resolves successfully as both TCP and UDP. String names depend upon /etc/services to determine whether TCP, UDP or both are valid for each service.

The string addrs is a set of one or more whitespace-separated addresses. Each address may consist of either service or bind,service where bind is taken to be "any address" if it is omitted as in the first form. Each address listed might return multiple socket addresses (for instance, specifying just "domain" is likely to return four sockets, TCP/IPv4, UDP/IPv4, TCP/IPv6 and UDP/IPv6).

If the string in addrs cannot be interpreted (usually because one of the component names is too long), the function will fail (returning 0) and errno will be set to EDOM. If resolving fails, errno will be set to EADDRNOTAVAIL, and the error may be further found from ipaddr_resolve_errstr.

See also
ip_servers2() for more details.