Apache Portable Runtime
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions

Modules

 Socket option definitions
 
 IP Protocol Definitions for use when creating sockets
 
 IP Multicast
 

Data Structures

struct  in_addr
 
struct  apr_sockaddr_t
 
struct  apr_hdtr_t
 

Macros

#define APR_MAX_SECS_TO_LINGER   30
 
#define APRMAXHOSTLEN   256
 
#define APR_ANYADDR   "0.0.0.0"
 
#define APR_IPV4_ADDR_OK   0x01
 
#define APR_IPV6_ADDR_OK   0x02
 
#define APR_INADDR_NONE   ((unsigned int) 0xffffffff)
 
#define APR_INET   AF_INET
 
#define APR_UNSPEC   0
 

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
 

Enumerations

enum  apr_shutdown_how_e { APR_SHUTDOWN_READ, APR_SHUTDOWN_WRITE, APR_SHUTDOWN_READWRITE }
 
enum  apr_interface_e { APR_LOCAL, APR_REMOTE }
 

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(*cleanup)(void *))
 
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_tapr_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)
 

Detailed Description

Macro Definition Documentation

#define APR_ANYADDR   "0.0.0.0"

Default 'any' address

#define APR_INADDR_NONE   ((unsigned int) 0xffffffff)

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

#define APR_INET   AF_INET

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

#define APR_IPV4_ADDR_OK   0x01
#define APR_IPV6_ADDR_OK   0x02
#define APR_MAX_SECS_TO_LINGER   30

Maximum seconds to linger

#define APR_UNSPEC   0

Let the system decide which address family to use

#define APRMAXHOSTLEN   256

Maximum hostname length

Typedef Documentation

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

A structure to represent an IP subnet

typedef apr_uint16_t apr_port_t
Remarks
use apr_uint16_t just in case some system has a short that isn't 16 bits...
Remarks
It's defined here as I think it should all be platform safe...
See also
apr_sockaddr_t
typedef struct apr_socket_t apr_socket_t

The specific declaration of inet_addr's ... some platforms fall back inet_network (this is not good, but necessary)A structure to represent sockets

Enumeration Type Documentation

Enum used to denote either the local and remote endpoint of a connection.

Enumerator
APR_LOCAL 

Socket information for local end of connection

APR_REMOTE 

Socket information for remote end of connection

Define what type of socket shutdown should occur.

Enumerator
APR_SHUTDOWN_READ 

no longer allow read request

APR_SHUTDOWN_WRITE 

no longer allow write requests

APR_SHUTDOWN_READWRITE 

no longer allow read or write requests

Function Documentation

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

Get name of the current machine

Parameters
bufA buffer to store the hostname in.
lenThe maximum length of the hostname that can be stored in the buffer provided. The suggested length is APRMAXHOSTLEN + 1.
contThe pool to use.
Remarks
If the buffer was not large enough, an error will be returned.
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.

Parameters
hostnameThe hostname.
saThe apr_sockaddr_t.
flagsSpecial processing flags.
Remarks
Results can vary significantly between platforms when processing wildcard socket addresses.
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
sockaddrThe apr_sockaddr_t that will have its port set
servnameThe 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
ipsubThe new ip-subnet representation
ipstrThe input IP address string
mask_or_numbitsThe input netmask or number-of-bits string, or NULL
pThe 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
ipsubThe ip-subnet representation
saThe socket address to test
Returns
non-zero if the socket address is within the subnet, 0 otherwise
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)

Parameters
addrThe new buffer containing just the hostname. On output, *addr will be NULL if no hostname/IP address was specfied.
scope_idThe new buffer containing just the scope id. On output, *scope_id will be NULL if no scope id was specified.
portThe port number. On output, *port will be 0 if no port was specified.

FIXME: 0 is a legal port (per RFC 1700). this should

return something besides zero if the port is missing.

Parameters
strThe input string to be parsed.
pThe pool from which *addr and *scope_id are allocated.
Remarks
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.
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.

Parameters
addr1One of the APR socket addresses.
addr2The other APR socket address.
Remarks
The return value will be non-zero if the addresses are equivalent.
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
saThe new apr_sockaddr_t.
hostnameThe hostname or numeric address string to resolve/parse, or NULL to build an address that corresponds to 0.0.0.0 or ::
familyThe address family to use, or APR_UNSPEC if the system should decide.
portThe port number.
flagsSpecial 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
pThe pool for the apr_sockaddr_t and associated storage.
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
addrThe IP address.
sockaddrThe 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
sockaddrThe socket address to reference.
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).

Parameters
addrThe APR socket address to examine.
Remarks
The return value will be non-zero if the address is initialized and is the wildcard address.
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

Parameters
new_sockA 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.
sockThe socket we are listening on.
connection_poolThe pool for the new 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.
apr_status_t apr_socket_accept_filter ( apr_socket_t sock,
char *  name,
char *  args 
)

Set an OS level accept filter.

Parameters
sockThe socket to put the accept filter on.
nameThe accept filter
argsAny extra args to the accept filter. Passing NULL here removes the accept filter.
Bug:
name and args should have been declared as const char *, as they are in APR 2.0
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
saThe returned apr_sockaddr_t.
whichWhether to retrieve the local or remote address
sockThe socket to use
apr_status_t apr_socket_atmark ( apr_socket_t sock,
int *  atmark 
)

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

Parameters
sockThe socket to query
atmarkIs set to true if socket is at the OOB/urgent mark, otherwise is set to false.
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
sockThe socket to check
atreadeofIf 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_socket_bind ( apr_socket_t sock,
apr_sockaddr_t sa 
)

Bind the socket to its associated port

Parameters
sockThe socket to bind
saThe socket address to bind to
Remarks
This may be where we will find out if there is any other process using the selected port.
apr_status_t apr_socket_close ( apr_socket_t thesocket)

Close a socket.

Parameters
thesocketThe socket to close
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
sockThe socket we wish to use for our side of the connection
saThe address of the machine we wish to connect to.
apr_status_t apr_socket_create ( apr_socket_t **  new_sock,
int  family,
int  type,
int  protocol,
apr_pool_t cont 
)

Create a socket.

Parameters
new_sockThe new socket that has been set up.
familyThe address family of the socket (e.g., APR_INET).
typeThe type of the socket (e.g., SOCK_STREAM).
protocolThe protocol of the socket (e.g., APR_PROTO_TCP).
contThe pool for the apr_socket_t and associated storage.
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.
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
dataThe user data associated with the socket.
keyThe key to associate with the user data.
sockThe 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
sockThe currently open socket.
dataThe user data to associate with the socket.
keyThe key to associate with the data.
cleanupThe cleanup to call when the socket is destroyed.
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.

apr_status_t apr_socket_listen ( apr_socket_t sock,
apr_int32_t  backlog 
)

Listen to a bound socket for connections.

Parameters
sockThe socket to listen on
backlogThe 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_opt_get ( apr_socket_t sock,
apr_int32_t  opt,
apr_int32_t *  on 
)

Query socket options for the specified socket

Parameters
sockThe socket to query
optThe 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)
onSocket option returned on the call.
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
sockThe socket to set up.
optThe 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 APR_STATUS_IS_EAGAIN() 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
onValue for the option.
apr_pool_t* apr_socket_pool_get ( const apr_socket_t thesocket)

Get the pool used by the socket.

apr_status_t apr_socket_protocol_get ( apr_socket_t sock,
int *  protocol 
)

Return the protocol of the socket.

Parameters
sockThe socket to query.
protocolThe returned protocol (e.g., APR_PROTO_TCP).
apr_status_t apr_socket_recv ( apr_socket_t sock,
char *  buf,
apr_size_t *  len 
)

Read data from a network.

Parameters
sockThe socket to read the data from.
bufThe buffer to store the data in.
lenOn entry, the number of bytes to receive; on exit, the number of bytes received.
Remarks
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.
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
fromUpdated with the address from which the data was received
sockThe socket to use
flagsThe flags to use
bufThe buffer to use
lenThe length of the available buffer
apr_status_t apr_socket_send ( apr_socket_t sock,
const char *  buf,
apr_size_t *  len 
)

Send data over a network.

Parameters
sockThe socket to send the data over.
bufThe buffer which contains the data to be sent.
lenOn entry, the number of bytes to send; on exit, the number of bytes sent.
Remarks
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.
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

Parameters
sockThe socket to which we're writing
fileThe open file from which to read
hdtrA structure containing the headers and trailers to send
offsetOffset 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
flagsAPR flags that are mapped to OS specific flags
Remarks
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.
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
sockThe socket to send from
whereThe apr_sockaddr_t describing where to send the data
flagsThe flags to use
bufThe data to send
lenThe length of the data to send
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.

Parameters
sockThe socket to send the data over.
vecThe array of iovec structs containing the data to send
nvecThe number of iovec structs in the array
lenReceives the number of bytes actually written
Remarks
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.
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.

Parameters
thesocketThe socket to close
howHow 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
Remarks
This does not actually close the socket descriptor, it just controls which calls are still valid on the socket.
apr_status_t apr_socket_timeout_get ( apr_socket_t sock,
apr_interval_time_t t 
)

Query socket timeout for the specified socket

Parameters
sockThe socket to query
tSocket timeout returned from the query.
apr_status_t apr_socket_timeout_set ( apr_socket_t sock,
apr_interval_time_t  t 
)

Setup socket timeout for the specified socket

Parameters
sockThe socket to set up.
tValue 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_type_get ( apr_socket_t sock,
int *  type 
)

Return the type of the socket.

Parameters
sockThe socket to query.
typeThe returned type (e.g., SOCK_STREAM).