Network Routines
[Apache Portability Runtime library]

Data Structures

struct  apr_sockaddr_t
struct  apr_hdtr_t

Modules

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

Defines

#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
#define APR_INET6   AF_INET6
#define apr_inet_addr   inet_addr
#define APR_SENDFILE_DISCONNECT_SOCKET   1

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_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)
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)

Define 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_INET6   AF_INET6

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

#define apr_inet_addr   inet_addr

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

#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_SENDFILE_DISCONNECT_SOCKET   1

Support reusing the socket on platforms which support it (from disconnect, specifically Win32.

Remarks:
Optional flag passed into apr_socket_sendfile()
#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

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:
buf A buffer to store the hostname in.
Parameters:
len The maximum length of the hostname that can be stored in the buffer provided. The suggested length is APRMAXHOSTLEN + 1.
Parameters:
cont The 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:
hostname The hostname.
Parameters:
sa The apr_sockaddr_t.
Parameters:
flags Special processing flags.
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
Parameters:
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
Parameters:
ipstr The input IP address string
Parameters:
mask_or_numbits The input netmask or number-of-bits string, or NULL
Parameters:
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
Parameters:
sa The 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::1]:80 (IPv6 numeric address string only) [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:
addr The new buffer containing just the hostname. On output, *addr will be NULL if no hostname/IP address was specfied.
Parameters:
scope_id The new buffer containing just the scope id. On output, *scope_id will be NULL if no scope id was specified.
Parameters:
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 ### return something besides zero if the port is missing.
Parameters:
str The input string to be parsed.
Parameters:
p The 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:
addr1 One of the APR socket addresses.
Parameters:
addr2 The 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:
sa The new apr_sockaddr_t.
Parameters:
hostname The hostname or numeric address string to resolve/parse, or NULL to build an address that corresponds to 0.0.0.0 or ::
Parameters:
family The address family to use, or APR_UNSPEC if the system should decide.
Parameters:
port The port number.
Parameters:
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
 
Parameters:
p The 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:
addr The IP address.
Parameters:
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.
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_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.
Parameters:
sock The socket we are listening on.
Parameters:
connection_pool The pool for the new socket.
apr_status_t apr_socket_accept_filter ( apr_socket_t sock,
char *  name,
char *  args 
)

Set an OS level accept filter.

Parameters:
sock The socket to put the accept filter on.
Parameters:
name The accept filter
Parameters:
args Any extra args to the accept filter. Passing NULL here removes the accept filter.
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 the address of the peer to which the socket is connected.

Parameters:
sa The returned apr_sockaddr_t.
Parameters:
which Whether to retrieve the local or remote address
Parameters:
sock The 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:
sock The socket to query
Parameters:
atmark Is set to true if socket is at the OOB/urgent mark, otherwise is set to false.
apr_status_t apr_socket_bind ( apr_socket_t sock,
apr_sockaddr_t sa 
)

Bind the socket to its associated port

Parameters:
sock The socket to bind
Parameters:
sa The 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:
thesocket The 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:
sock The socket we wish to use for our side of the connection
Parameters:
sa The 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_sock The new socket that has been set up.
Parameters:
family The address family of the socket (e.g., APR_INET).
Parameters:
type The type of the socket (e.g., SOCK_STREAM).
Parameters:
protocol The protocol of the socket (e.g., APR_PROTO_TCP).
Parameters:
cont The pool for the apr_socket_t and associated storage.
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.
Parameters:
key The key to associate with the user data.
Parameters:
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.
Parameters:
data The user data to associate with the socket.
Parameters:
key The key to associate with the data.
Parameters:
cleanup The 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:
sock The socket to listen on
Parameters:
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_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
Parameters:
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)
 
Parameters:
on Socket 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:
sock The socket to set up.
Parameters:
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 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
 
Parameters:
on Value 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:
sock The socket to query.
Parameters:
protocol The 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:
sock The socket to read the data from.
Parameters:
buf The buffer to store the data in.
Parameters:
len On 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

Parameters:
from parameter, and the
Parameters:
len parameter is updated to give the number of bytes written to
Parameters:
buf. 
Parameters:
from Updated with the address from which the data was received
Parameters:
sock The socket to use
Parameters:
flags The flags to use
Parameters:
buf The buffer to use
Parameters:
len The 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:
sock The socket to send the data over.
Parameters:
buf The buffer which contains the data to be sent.
Parameters:
len On 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:
sock The socket to which we're writing
Parameters:
file The open file from which to read
Parameters:
hdtr A structure containing the headers and trailers to send
Parameters:
offset Offset into the file where we should begin writing
Parameters:
len (input) - Number of bytes to send from the file (output) - Number of bytes actually sent, including headers, file, and trailers
Parameters:
flags APR 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:
sock The socket to send from
Parameters:
where The apr_sockaddr_t describing where to send the data
Parameters:
flags The flags to use
Parameters:
buf The data to send
Parameters:
len The 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 packets of data over a network.

Parameters:
sock The socket to send the data over.
Parameters:
vec The array of iovec structs containing the data to send
Parameters:
nvec The number of iovec structs in the array
Parameters:
len Receives 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 3.
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:
thesocket The socket to close
Parameters:
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
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:
sock The socket to query
Parameters:
t Socket 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:
sock The socket to set up.
Parameters:
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_type_get ( apr_socket_t sock,
int *  type 
)

Return the type of the socket.

Parameters:
sock The socket to query.
Parameters:
type The returned type (e.g., SOCK_STREAM).
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines
Generated on Tue Jul 26 15:20:31 2011 for Apache Portable Runtime by  doxygen 1.6.3