Network Routines

Overview

IP Multicast

IP Protocol Definitions for use when creating sockets

Socket option definitions

// typedefs

typedef struct apr_socket_t apr_socket_t;
typedef struct apr_hdtr_t apr_hdtr_t;
typedef struct in_addr apr_in_addr_t;
typedef struct apr_ipsubnet_t apr_ipsubnet_t;
typedef apr_uint16_t apr_port_t;
typedef struct apr_sockaddr_t apr_sockaddr_t;

// enums

enum apr_interface_e;
enum apr_shutdown_how_e;

// structs

struct apr_hdtr_t;
struct apr_sockaddr_t;

// global functions

apr_status_t
apr_socket_create(
    apr_socket_t** new_sock,
    int family,
    int type,
    int protocol,
    apr_pool_t* cont
);

apr_status_t
apr_socket_shutdown(
    apr_socket_t* thesocket,
    apr_shutdown_how_e how
);

apr_status_t
apr_socket_close(apr_socket_t* thesocket);

apr_status_t
apr_socket_bind(
    apr_socket_t* sock,
    apr_sockaddr_t* sa
);

apr_status_t
apr_socket_listen(
    apr_socket_t* sock,
    apr_int32_t backlog
);

apr_status_t
apr_socket_accept(
    apr_socket_t** new_sock,
    apr_socket_t* sock,
    apr_pool_t* connection_pool
);

apr_status_t
apr_socket_connect(
    apr_socket_t* sock,
    apr_sockaddr_t* sa
);

apr_status_t
apr_socket_atreadeof(
    apr_socket_t* sock,
    int* atreadeof
);

apr_status_t
apr_sockaddr_info_get(
    apr_sockaddr_t** sa,
    const char* hostname,
    apr_int32_t family,
    apr_port_t port,
    apr_int32_t flags,
    apr_pool_t* p
);

apr_status_t
apr_getnameinfo(
    char** hostname,
    apr_sockaddr_t* sa,
    apr_int32_t flags
);

apr_status_t
apr_parse_addr_port(
    char** addr,
    char** scope_id,
    apr_port_t* port,
    const char* str,
    apr_pool_t* p
);

apr_status_t
apr_gethostname(
    char* buf,
    int len,
    apr_pool_t* cont
);

apr_status_t
apr_socket_data_get(
    void** data,
    const char* key,
    apr_socket_t* sock
);

apr_status_t
apr_socket_data_set(
    apr_socket_t* sock,
    void* data,
    const char* key,
    apr_status_t(*)(void*) cleanup
);

apr_status_t
apr_socket_send(
    apr_socket_t* sock,
    const char* buf,
    apr_size_t* len
);

apr_status_t
apr_socket_sendv(
    apr_socket_t* sock,
    const struct iovec* vec,
    apr_int32_t nvec,
    apr_size_t* len
);

apr_status_t
apr_socket_sendto(
    apr_socket_t* sock,
    apr_sockaddr_t* where,
    apr_int32_t flags,
    const char* buf,
    apr_size_t* len
);

apr_status_t
apr_socket_recvfrom(
    apr_sockaddr_t* from,
    apr_socket_t* sock,
    apr_int32_t flags,
    char* buf,
    apr_size_t* len
);

apr_status_t
apr_socket_sendfile(
    apr_socket_t* sock,
    apr_file_t* file,
    apr_hdtr_t* hdtr,
    apr_off_t* offset,
    apr_size_t* len,
    apr_int32_t flags
);

apr_status_t
apr_socket_recv(
    apr_socket_t* sock,
    char* buf,
    apr_size_t* len
);

apr_status_t
apr_socket_opt_set(
    apr_socket_t* sock,
    apr_int32_t opt,
    apr_int32_t on
);

apr_status_t
apr_socket_timeout_set(
    apr_socket_t* sock,
    apr_interval_time_t t
);

apr_status_t
apr_socket_opt_get(
    apr_socket_t* sock,
    apr_int32_t opt,
    apr_int32_t* on
);

apr_status_t
apr_socket_timeout_get(
    apr_socket_t* sock,
    apr_interval_time_t* t
);

apr_status_t
apr_socket_atmark(
    apr_socket_t* sock,
    int* atmark
);

apr_status_t
apr_socket_addr_get(
    apr_sockaddr_t** sa,
    apr_interface_e which,
    apr_socket_t* sock
);

apr_status_t
apr_sockaddr_ip_get(
    char** addr,
    apr_sockaddr_t* sockaddr
);

apr_status_t
apr_sockaddr_ip_getbuf(
    char* buf,
    apr_size_t buflen,
    apr_sockaddr_t* sockaddr
);

int
apr_sockaddr_equal(
    const apr_sockaddr_t* addr1,
    const apr_sockaddr_t* addr2
);

int
apr_sockaddr_is_wildcard(const apr_sockaddr_t* addr);

apr_status_t
apr_socket_type_get(
    apr_socket_t* sock,
    int* type
);

apr_status_t
apr_getservbyname(
    apr_sockaddr_t* sockaddr,
    const char* servname
);

apr_status_t
apr_ipsubnet_create(
    apr_ipsubnet_t** ipsub,
    const char* ipstr,
    const char* mask_or_numbits,
    apr_pool_t* p
);

int
apr_ipsubnet_test(
    apr_ipsubnet_t* ipsub,
    apr_sockaddr_t* sa
);

apr_status_t
apr_socket_accept_filter(
    apr_socket_t* sock,
    char* name,
    char* args
);

apr_status_t
apr_socket_protocol_get(
    apr_socket_t* sock,
    int* protocol
);

apr_pool_t*
apr_socket_pool_get(const apr_socket_t* thesocket);

apr_status_t
apr_socket_inherit_set(apr_socket_t* thesocket);

apr_status_t
apr_socket_inherit_unset(apr_socket_t* thesocket);

// macros

#define APRMAXHOSTLEN
#define APR_ANYADDR
#define APR_INADDR_NONE
#define APR_INET
#define APR_INET6
#define APR_IPV4_ADDR_OK
#define APR_IPV6_ADDR_OK
#define APR_MAX_SECS_TO_LINGER
#define APR_SENDFILE_DISCONNECT_SOCKET
#define APR_UNSPEC
#define apr_inet_addr

Detailed Documentation

Typedefs

typedef struct apr_socket_t apr_socket_t

A structure to represent sockets

typedef struct apr_hdtr_t apr_hdtr_t

A structure to encapsulate headers and trailers for apr_socket_sendfile

typedef struct in_addr apr_in_addr_t

A structure to represent in_addr

typedef struct apr_ipsubnet_t apr_ipsubnet_t

A structure to represent an IP subnet

typedef apr_uint16_t apr_port_t

use apr_uint16_t just in case some system has a short that isn’t 16 bits…

typedef struct apr_sockaddr_t apr_sockaddr_t

It’s defined here as I think it should all be platform safe…

See also:

apr_sockaddr_t

Global Functions

apr_status_t
apr_socket_create(
    apr_socket_t** new_sock,
    int family,
    int type,
    int protocol,
    apr_pool_t* cont
)

Create a socket.

Note

The pool will be used by various functions that operate on the socket. The caller must ensure that it is not used by other threads at the same time.

Parameters:

new_sock	The new socket that has been set up.
family	The address family of the socket (e.g., APR_INET).
type	The type of the socket (e.g., SOCK_STREAM).
protocol	The protocol of the socket (e.g., APR_PROTO_TCP).
cont	The pool for the apr_socket_t and associated storage.

apr_status_t
apr_socket_shutdown(
    apr_socket_t* thesocket,
    apr_shutdown_how_e how
)

Shutdown either reading, writing, or both sides of a socket. This does not actually close the socket descriptor, it just controls which calls are still valid on the socket.

Parameters:

thesocket	The socket to close
how	How to shutdown the socket. One of: APR_SHUTDOWN_READ no longer allow read requests APR_SHUTDOWN_WRITE no longer allow write requests APR_SHUTDOWN_READWRITE no longer allow read or write requests

See also:

apr_shutdown_how_e

apr_status_t
apr_socket_close(apr_socket_t* thesocket)

Close a socket.

Parameters:

thesocket

The socket to close

apr_status_t
apr_socket_bind(
    apr_socket_t* sock,
    apr_sockaddr_t* sa
)

Bind the socket to its associated port This may be where we will find out if there is any other process using the selected port.

Parameters:

sock	The socket to bind
sa	The socket address to bind to

apr_status_t
apr_socket_listen(
    apr_socket_t* sock,
    apr_int32_t backlog
)

Listen to a bound socket for connections.

Parameters:

sock	The socket to listen on
backlog	The number of outstanding connections allowed in the sockets listen queue. If this value is less than zero, the listen queue size is set to zero.

apr_status_t
apr_socket_accept(
    apr_socket_t** new_sock,
    apr_socket_t* sock,
    apr_pool_t* connection_pool
)

Accept a new connection request

Note

The pool will be used by various functions that operate on the socket. The caller must ensure that it is not used by other threads at the same time.

Parameters:

new_sock	A copy of the socket that is connected to the socket that made the connection request. This is the socket which should be used for all future communication.
sock	The socket we are listening on.
connection_pool	The pool for the new socket.

apr_status_t
apr_socket_connect(
    apr_socket_t* sock,
    apr_sockaddr_t* sa
)

Issue a connection request to a socket either on the same machine or a different one.

Parameters:

sock	The socket we wish to use for our side of the connection
sa	The address of the machine we wish to connect to.

apr_status_t
apr_socket_atreadeof(
    apr_socket_t* sock,
    int* atreadeof
)

Determine whether the receive part of the socket has been closed by the peer (such that a subsequent call to apr_socket_read would return APR_EOF), if the socket’s receive buffer is empty. This function does not block waiting for I/O.

Parameters:

sock	The socket to check
atreadeof	If APR_SUCCESS is returned, *atreadeof is set to non-zero if a subsequent read would return APR_EOF

Returns:

an error is returned if it was not possible to determine the status, in which case *atreadeof is not changed.

apr_status_t
apr_sockaddr_info_get(
    apr_sockaddr_t** sa,
    const char* hostname,
    apr_int32_t family,
    apr_port_t port,
    apr_int32_t flags,
    apr_pool_t* p
)

Create apr_sockaddr_t from hostname, address family, and port.

Parameters:

sa	The new apr_sockaddr_t.
hostname	The hostname or numeric address string to resolve/parse, or NULL to build an address that corresponds to 0.0.0.0 or ::
family	The address family to use, or APR_UNSPEC if the system should decide.
port	The port number.
flags	Special processing flags: APR_IPV4_ADDR_OK first query for IPv4 addresses; only look for IPv6 addresses if the first query failed; only valid if family is APR_UNSPEC and hostname isn't NULL; mutually exclusive with APR_IPV6_ADDR_OK APR_IPV6_ADDR_OK first query for IPv6 addresses; only look for IPv4 addresses if the first query failed; only valid if family is APR_UNSPEC and hostname isn't NULL and APR_HAVE_IPV6; mutually exclusive with APR_IPV4_ADDR_OK
p	The pool for the apr_sockaddr_t and associated storage.

apr_status_t
apr_getnameinfo(
    char** hostname,
    apr_sockaddr_t* sa,
    apr_int32_t flags
)

Look up the host name from an apr_sockaddr_t. Results can vary significantly between platforms when processing wildcard socket addresses.

Parameters:

hostname	The hostname.
sa	The apr_sockaddr_t.
flags	Special processing flags.

apr_status_t
apr_parse_addr_port(
    char** addr,
    char** scope_id,
    apr_port_t* port,
    const char* str,
    apr_pool_t* p
)

Parse hostname/IP address with scope id and port.

Any of the following strings are accepted: 8080 (just the port number) www.apache.org (just the hostname) www.apache.org:8080 (hostname and port number)

[fe80::1eth0] (IPv6 numeric address string and scope id)

Invalid strings: (empty string) [abc] (not valid IPv6 numeric address string) abc:65536 (invalid port number)

return something besides zero if the port is missing.

If scope id shouldn’t be allowed, check for scope_id != NULL in addition to checking the return code. If addr/hostname should be required, check for addr == NULL in addition to checking the return code.

Parameters:

addr	The new buffer containing just the hostname. On output, *addr will be NULL if no hostname/IP address was specfied.
scope_id	The new buffer containing just the scope id. On output, *scope_id will be NULL if no scope id was specified.
port	The port number. On output, *port will be 0 if no port was specified. FIXME: 0 is a legal port (per RFC 1700). this should
str	The input string to be parsed.
p	The pool from which *addr and *scope_id are allocated.

apr_status_t
apr_gethostname(
    char* buf,
    int len,
    apr_pool_t* cont
)

Get name of the current machine If the buffer was not large enough, an error will be returned.

Parameters:

buf	A buffer to store the hostname in.
len	The maximum length of the hostname that can be stored in the buffer provided. The suggested length is APRMAXHOSTLEN + 1.
cont	The pool to use.

apr_status_t
apr_socket_data_get(
    void** data,
    const char* key,
    apr_socket_t* sock
)

Return the data associated with the current socket

Parameters:

data	The user data associated with the socket.
key	The key to associate with the user data.
sock	The currently open socket.

apr_status_t
apr_socket_data_set(
    apr_socket_t* sock,
    void* data,
    const char* key,
    apr_status_t(*)(void*) cleanup
)

Set the data associated with the current socket.

Parameters:

sock	The currently open socket.
data	The user data to associate with the socket.
key	The key to associate with the data.
cleanup	The cleanup to call when the socket is destroyed.

apr_status_t
apr_socket_send(
    apr_socket_t* sock,
    const char* buf,
    apr_size_t* len
)

Send data over a network… code-block:: none

This functions acts like a blocking write by default. To change this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK socket option.

It is possible for both bytes to be sent and an error to be returned.

APR_EINTR is never returned.

Parameters:

sock	The socket to send the data over.
buf	The buffer which contains the data to be sent.
len	On entry, the number of bytes to send; on exit, the number of bytes sent.

apr_status_t
apr_socket_sendv(
    apr_socket_t* sock,
    const struct iovec* vec,
    apr_int32_t nvec,
    apr_size_t* len
)

Send multiple buffers over a network… code-block:: none

This functions acts like a blocking write by default. To change this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK socket option. The number of bytes actually sent is stored in argument 4.

It is possible for both bytes to be sent and an error to be returned.

APR_EINTR is never returned.

Parameters:

sock	The socket to send the data over.
vec	The array of iovec structs containing the data to send
nvec	The number of iovec structs in the array
len	Receives the number of bytes actually written

apr_status_t
apr_socket_sendto(
    apr_socket_t* sock,
    apr_sockaddr_t* where,
    apr_int32_t flags,
    const char* buf,
    apr_size_t* len
)

Parameters:

sock	The socket to send from
where	The apr_sockaddr_t describing where to send the data
flags	The flags to use
buf	The data to send
len	The length of the data to send

apr_status_t
apr_socket_recvfrom(
    apr_sockaddr_t* from,
    apr_socket_t* sock,
    apr_int32_t flags,
    char* buf,
    apr_size_t* len
)

Read data from a socket. On success, the address of the peer from which the data was sent is copied into the from parameter, and the len parameter is updated to give the number of bytes written to buf.

Parameters:

from	Updated with the address from which the data was received
sock	The socket to use
flags	The flags to use
buf	The buffer to use
len	The length of the available buffer

apr_status_t
apr_socket_sendfile(
    apr_socket_t* sock,
    apr_file_t* file,
    apr_hdtr_t* hdtr,
    apr_off_t* offset,
    apr_size_t* len,
    apr_int32_t flags
)

Send a file from an open file descriptor to a socket, along with optional headers and trailers This functions acts like a blocking write by default. To change this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK socket option. The number of bytes actually sent is stored in the len parameter. The offset parameter is passed by reference for no reason; its value will never be modified by the apr_socket_sendfile() function.

Parameters:

sock	The socket to which we’re writing
file	The open file from which to read
hdtr	A structure containing the headers and trailers to send
offset	Offset into the file where we should begin writing
len	(input) - Number of bytes to send from the file (output) - Number of bytes actually sent, including headers, file, and trailers
flags	APR flags that are mapped to OS specific flags

apr_status_t
apr_socket_recv(
    apr_socket_t* sock,
    char* buf,
    apr_size_t* len
)

Read data from a network… code-block:: none

This functions acts like a blocking read by default. To change this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK socket option. The number of bytes actually received is stored in argument 3.

It is possible for both bytes to be received and an APR_EOF or other error to be returned.

APR_EINTR is never returned.

Parameters:

sock	The socket to read the data from.
buf	The buffer to store the data in.
len	On entry, the number of bytes to receive; on exit, the number of bytes received.

apr_status_t
apr_socket_opt_set(
    apr_socket_t* sock,
    apr_int32_t opt,
    apr_int32_t on
)

Setup socket options for the specified socket

Parameters:

sock	The socket to set up.
opt	The option we would like to configure. One of: APR_SO_DEBUG -- turn on debugging information APR_SO_KEEPALIVE -- keep connections active APR_SO_LINGER -- lingers on close if data is present APR_SO_NONBLOCK -- Turns blocking on/off for socket When this option is enabled, use the :ref:`APR_STATUS_IS_EAGAIN() <doxid-group___a_p_r___s_t_a_t_u_s___i_s_1ga9dd578bfcd76a2d997395608ae5b3a4e>` macro to see if a send or receive function could not transfer data without blocking. APR_SO_REUSEADDR -- The rules used in validating addresses supplied to bind should allow reuse of local addresses. APR_SO_SNDBUF -- Set the SendBufferSize APR_SO_RCVBUF -- Set the ReceiveBufferSize
on	Value for the option.

apr_status_t
apr_socket_timeout_set(
    apr_socket_t* sock,
    apr_interval_time_t t
)

Setup socket timeout for the specified socket

Parameters:

sock	The socket to set up.
t	Value for the timeout. t > 0 read and write calls return APR_TIMEUP if specified time elapsess with no data read or written t == 0 read and write calls never block t < 0 read and write calls block

apr_status_t
apr_socket_opt_get(
    apr_socket_t* sock,
    apr_int32_t opt,
    apr_int32_t* on
)

Query socket options for the specified socket

Parameters:

sock	The socket to query
opt	The option we would like to query. One of: APR_SO_DEBUG -- turn on debugging information APR_SO_KEEPALIVE -- keep connections active APR_SO_LINGER -- lingers on close if data is present APR_SO_NONBLOCK -- Turns blocking on/off for socket APR_SO_REUSEADDR -- The rules used in validating addresses supplied to bind should allow reuse of local addresses. APR_SO_SNDBUF -- Set the SendBufferSize APR_SO_RCVBUF -- Set the ReceiveBufferSize APR_SO_DISCONNECTED -- Query the disconnected state of the socket. (Currently only used on Windows)
on	Socket option returned on the call.

apr_status_t
apr_socket_timeout_get(
    apr_socket_t* sock,
    apr_interval_time_t* t
)

Query socket timeout for the specified socket

Parameters:

sock	The socket to query
t	Socket timeout returned from the query.

apr_status_t
apr_socket_atmark(
    apr_socket_t* sock,
    int* atmark
)

Query the specified socket if at the OOB/Urgent data mark

Parameters:

sock	The socket to query
atmark	Is set to true if socket is at the OOB/urgent mark, otherwise is set to false.

apr_status_t
apr_socket_addr_get(
    apr_sockaddr_t** sa,
    apr_interface_e which,
    apr_socket_t* sock
)

Return an address associated with a socket; either the address to which the socket is bound locally or the address of the peer to which the socket is connected.

Parameters:

sa	The returned apr_sockaddr_t.
which	Whether to retrieve the local or remote address
sock	The socket to use

apr_status_t
apr_sockaddr_ip_get(
    char** addr,
    apr_sockaddr_t* sockaddr
)

Return the IP address (in numeric address string format) in an APR socket address. APR will allocate storage for the IP address string from the pool of the apr_sockaddr_t.

Parameters:

addr	The IP address.
sockaddr	The socket address to reference.

apr_status_t
apr_sockaddr_ip_getbuf(
    char* buf,
    apr_size_t buflen,
    apr_sockaddr_t* sockaddr
)

Write the IP address (in numeric address string format) of the APR socket address sockaddr into the buffer buf (of size buflen).

Parameters:

sockaddr

The socket address to reference.

int
apr_sockaddr_equal(
    const apr_sockaddr_t* addr1,
    const apr_sockaddr_t* addr2
)

See if the IP addresses in two APR socket addresses are equivalent. Appropriate logic is present for comparing IPv4-mapped IPv6 addresses with IPv4 addresses.

The return value will be non-zero if the addresses are equivalent.

Parameters:

addr1	One of the APR socket addresses.
addr2	The other APR socket address.

int
apr_sockaddr_is_wildcard(const apr_sockaddr_t* addr)

See if the IP address in an APR socket address refers to the wildcard address for the protocol family (e.g., INADDR_ANY for IPv4).

The return value will be non-zero if the address is initialized and is the wildcard address.

Parameters:

addr	The APR socket address to examine.

apr_status_t
apr_socket_type_get(
    apr_socket_t* sock,
    int* type
)

Return the type of the socket.

Parameters:

sock	The socket to query.
type	The returned type (e.g., SOCK_STREAM).

apr_status_t
apr_getservbyname(
    apr_sockaddr_t* sockaddr,
    const char* servname
)

Given an apr_sockaddr_t and a service name, set the port for the service

Parameters:

sockaddr	The apr_sockaddr_t that will have its port set
servname	The name of the service you wish to use

apr_status_t
apr_ipsubnet_create(
    apr_ipsubnet_t** ipsub,
    const char* ipstr,
    const char* mask_or_numbits,
    apr_pool_t* p
)

Build an ip-subnet representation from an IP address and optional netmask or number-of-bits.

Parameters:

ipsub	The new ip-subnet representation
ipstr	The input IP address string
mask_or_numbits	The input netmask or number-of-bits string, or NULL
p	The pool to allocate from

int
apr_ipsubnet_test(
    apr_ipsubnet_t* ipsub,
    apr_sockaddr_t* sa
)

Test the IP address in an apr_sockaddr_t against a pre-built ip-subnet representation.

Parameters:

ipsub	The ip-subnet representation
sa	The socket address to test

Returns:

non-zero if the socket address is within the subnet, 0 otherwise

apr_status_t
apr_socket_accept_filter(
    apr_socket_t* sock,
    char* name,
    char* args
)

Set an OS level accept filter. Bug name and args should have been declared as const char *, as they are in APR 2.0

Parameters:

sock	The socket to put the accept filter on.
name	The accept filter
args	Any extra args to the accept filter. Passing NULL here removes the accept filter.

apr_status_t
apr_socket_protocol_get(
    apr_socket_t* sock,
    int* protocol
)

Return the protocol of the socket.

Parameters:

sock	The socket to query.
protocol	The returned protocol (e.g., APR_PROTO_TCP).

apr_pool_t*
apr_socket_pool_get(const apr_socket_t* thesocket)

Get the pool used by the socket.

apr_status_t
apr_socket_inherit_set(apr_socket_t* thesocket)

Set a socket to be inherited by child processes.

apr_status_t
apr_socket_inherit_unset(apr_socket_t* thesocket)

Unset a socket from being inherited by child processes.

Macros

#define APRMAXHOSTLEN

Maximum hostname length

#define APR_ANYADDR

Default ‘any’ address

#define APR_INADDR_NONE

Not all platforms have a real INADDR_NONE. This macro replaces INADDR_NONE on all platforms.

#define APR_INET

Not all platforms have these defined, so we’ll define them here The default values come from FreeBSD 4.1.1

#define APR_INET6

IPv6 Address Family. Not all platforms may have this defined.

#define APR_IPV4_ADDR_OK

See also:

apr_sockaddr_info_get()

#define APR_IPV6_ADDR_OK

See also:

apr_sockaddr_info_get()

#define APR_MAX_SECS_TO_LINGER

Maximum seconds to linger

#define APR_SENDFILE_DISCONNECT_SOCKET

Support reusing the socket on platforms which support it (from disconnect, specifically Win32. Optional flag passed into apr_socket_sendfile()

#define APR_UNSPEC

Let the system decide which address family to use

#define apr_inet_addr

The specific declaration of inet_addr’s … some platforms fall back inet_network (this is not good, but necessary)