rubbos/app/apache2/include/apr_network_io.h

   1 /* Licensed to the Apache Software Foundation (ASF) under one or more
   2  * contributor license agreements.  See the NOTICE file distributed with
   3  * this work for additional information regarding copyright ownership.
   4  * The ASF licenses this file to You under the Apache License, Version 2.0
   5  * (the "License"); you may not use this file except in compliance with
   6  * the License.  You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef APR_NETWORK_IO_H
  18 #define APR_NETWORK_IO_H
  19 /**
  20  * @file apr_network_io.h
  21  * @brief APR Network library
  22  */
  23
  24 #include "apr.h"
  25 #include "apr_pools.h"
  26 #include "apr_file_io.h"
  27 #include "apr_errno.h"
  28 #include "apr_inherit.h"
  29
  30 #if APR_HAVE_NETINET_IN_H
  31 #include <netinet/in.h>
  32 #endif
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif /* __cplusplus */
  37
  38 /**
  39  * @defgroup apr_network_io Network Routines
  40  * @ingroup APR
  41  * @{
  42  */
  43
  44 #ifndef APR_MAX_SECS_TO_LINGER
  45 /** Maximum seconds to linger */
  46 #define APR_MAX_SECS_TO_LINGER 30
  47 #endif
  48
  49 #ifndef MAX_SECS_TO_LINGER
  50 /** @deprecated @see APR_MAX_SECS_TO_LINGER */
  51 #define MAX_SECS_TO_LINGER APR_MAX_SECS_TO_LINGER
  52 #endif
  53
  54 #ifndef APRMAXHOSTLEN
  55 /** Maximum hostname length */
  56 #define APRMAXHOSTLEN 256
  57 #endif
  58
  59 #ifndef APR_ANYADDR
  60 /** Default 'any' address */
  61 #define APR_ANYADDR "0.0.0.0"
  62 #endif
  63
  64 /**
  65  * @defgroup apr_sockopt Socket option definitions
  66  * @{
  67  */
  68 #define APR_SO_LINGER        1    /**< Linger */
  69 #define APR_SO_KEEPALIVE     2    /**< Keepalive */
  70 #define APR_SO_DEBUG         4    /**< Debug */
  71 #define APR_SO_NONBLOCK      8    /**< Non-blocking IO */
  72 #define APR_SO_REUSEADDR     16   /**< Reuse addresses */
  73 #define APR_SO_TIMEOUT       32   /**< Timeout */
  74 #define APR_SO_SNDBUF        64   /**< Send buffer */
  75 #define APR_SO_RCVBUF        128  /**< Receive buffer */
  76 #define APR_SO_DISCONNECTED  256  /**< Disconnected */
  77 #define APR_TCP_NODELAY      512  /**< For SCTP sockets, this is mapped
  78                                    * to STCP_NODELAY internally.
  79                                    */
  80 #define APR_TCP_NOPUSH       1024 /**< No push */
  81 #define APR_RESET_NODELAY    2048 /**< This flag is ONLY set internally
  82                                    * when we set APR_TCP_NOPUSH with
  83                                    * APR_TCP_NODELAY set to tell us that
  84                                    * APR_TCP_NODELAY should be turned on
  85                                    * again when NOPUSH is turned off
  86                                    */
  87 #define APR_INCOMPLETE_READ 4096  /**< Set on non-blocking sockets
  88                                    * (timeout != 0) on which the
  89                                    * previous read() did not fill a buffer
  90                                    * completely.  the next apr_socket_recv()
  91                                    * will first call select()/poll() rather than
  92                                    * going straight into read().  (Can also
  93                                    * be set by an application to force a
  94                                    * select()/poll() call before the next
  95                                    * read, in cases where the app expects
  96                                    * that an immediate read would fail.)
  97                                    */
  98 #define APR_INCOMPLETE_WRITE 8192 /**< like APR_INCOMPLETE_READ, but for write
  99                                    * @see APR_INCOMPLETE_READ
 100                                    */
 101 #define APR_IPV6_V6ONLY     16384 /**< Don't accept IPv4 connections on an
 102                                    * IPv6 listening socket.
 103                                    */
 104
 105 /** @} */
 106
 107 /** Define what type of socket shutdown should occur. */
 108 typedef enum {
 109     APR_SHUTDOWN_READ,          /**< no longer allow read request */
 110     APR_SHUTDOWN_WRITE,         /**< no longer allow write requests */
 111     APR_SHUTDOWN_READWRITE      /**< no longer allow read or write requests */
 112 } apr_shutdown_how_e;
 113
 114 #define APR_IPV4_ADDR_OK  0x01  /**< @see apr_sockaddr_info_get() */
 115 #define APR_IPV6_ADDR_OK  0x02  /**< @see apr_sockaddr_info_get() */
 116
 117 #if (!APR_HAVE_IN_ADDR)
 118 /**
 119  * We need to make sure we always have an in_addr type, so APR will just
 120  * define it ourselves, if the platform doesn't provide it.
 121  */
 122 struct in_addr {
 123     apr_uint32_t  s_addr; /**< storage to hold the IP# */
 124 };
 125 #endif
 126
 127 /**
 128  * @def APR_INET
 129  * Not all platforms have these defined, so we'll define them here
 130  * The default values come from FreeBSD 4.1.1
 131  */
 132 #define APR_INET     AF_INET
 133 /** @def APR_UNSPEC
 134  * Let the system decide which address family to use
 135  */
 136 #ifdef AF_UNSPEC
 137 #define APR_UNSPEC   AF_UNSPEC
 138 #else
 139 #define APR_UNSPEC   0
 140 #endif
 141 #if APR_HAVE_IPV6
 142 #define APR_INET6    AF_INET6
 143 #endif
 144
 145 /**
 146  * @defgroup IP_Proto IP Protocol Definitions for use when creating sockets
 147  * @{
 148  */
 149 #define APR_PROTO_TCP       6   /**< TCP  */
 150 #define APR_PROTO_UDP      17   /**< UDP  */
 151 #define APR_PROTO_SCTP    132   /**< SCTP */
 152 /** @} */
 153
 154 /**
 155  * Enum to tell us if we're interested in remote or local socket
 156  */
 157 typedef enum {
 158     APR_LOCAL,
 159     APR_REMOTE
 160 } apr_interface_e;
 161
 162 /**
 163  * The specific declaration of inet_addr's ... some platforms fall back
 164  * inet_network (this is not good, but necessary)
 165  */
 166
 167 #if APR_HAVE_INET_ADDR
 168 #define apr_inet_addr    inet_addr
 169 #elif APR_HAVE_INET_NETWORK        /* only DGUX, as far as I know */
 170 /**
 171  * @warning
 172  * not generally safe... inet_network() and inet_addr() perform
 173  * different functions */
 174 #define apr_inet_addr    inet_network
 175 #endif
 176
 177 /** A structure to represent sockets */
 178 typedef struct apr_socket_t     apr_socket_t;
 179 /**
 180  * A structure to encapsulate headers and trailers for apr_socket_sendfile
 181  */
 182 typedef struct apr_hdtr_t       apr_hdtr_t;
 183 /** A structure to represent in_addr */
 184 typedef struct in_addr          apr_in_addr_t;
 185 /** A structure to represent an IP subnet */
 186 typedef struct apr_ipsubnet_t apr_ipsubnet_t;
 187
 188 /** @remark use apr_uint16_t just in case some system has a short that isn't 16 bits... */
 189 typedef apr_uint16_t            apr_port_t;
 190
 191 /** @remark It's defined here as I think it should all be platform safe...
 192  * @see apr_sockaddr_t
 193  */
 194 typedef struct apr_sockaddr_t apr_sockaddr_t;
 195 /**
 196  * APRs socket address type, used to ensure protocol independence
 197  */
 198 struct apr_sockaddr_t {
 199     /** The pool to use... */
 200     apr_pool_t *pool;
 201     /** The hostname */
 202     char *hostname;
 203     /** Either a string of the port number or the service name for the port */
 204     char *servname;
 205     /** The numeric port */
 206     apr_port_t port;
 207     /** The family */
 208     apr_int32_t family;
 209     /** Union of either IPv4 or IPv6 sockaddr. */
 210     union {
 211         /** IPv4 sockaddr structure */
 212         struct sockaddr_in sin;
 213 #if APR_HAVE_IPV6
 214         /** IPv6 sockaddr structure */
 215         struct sockaddr_in6 sin6;
 216 #endif
 217     } sa;
 218     /** How big is the sockaddr we're using? */
 219     apr_socklen_t salen;
 220     /** How big is the ip address structure we're using? */
 221     int ipaddr_len;
 222     /** How big should the address buffer be?  16 for v4 or 46 for v6
 223      *  used in inet_ntop... */
 224     int addr_str_len;
 225     /** This points to the IP address structure within the appropriate
 226      *  sockaddr structure.  */
 227     void *ipaddr_ptr;
 228     /** If multiple addresses were found by apr_sockaddr_info_get(), this
 229      *  points to a representation of the next address. */
 230     apr_sockaddr_t *next;
 231 };
 232
 233 #if APR_HAS_SENDFILE
 234 /**
 235  * Support reusing the socket on platforms which support it (from disconnect,
 236  * specifically Win32.
 237  * @remark Optional flag passed into apr_socket_sendfile()
 238  */
 239 #define APR_SENDFILE_DISCONNECT_SOCKET      1
 240 #endif
 241
 242 /** A structure to encapsulate headers and trailers for apr_socket_sendfile */
 243 struct apr_hdtr_t {
 244     /** An iovec to store the headers sent before the file. */
 245     struct iovec* headers;
 246     /** number of headers in the iovec */
 247     int numheaders;
 248     /** An iovec to store the trailers sent after the file. */
 249     struct iovec* trailers;
 250     /** number of trailers in the iovec */
 251     int numtrailers;
 252 };
 253
 254 /* function definitions */
 255
 256 /**
 257  * Create a socket.
 258  * @remark With APR 1.0, this function follows the prototype
 259  * of apr_socket_create_ex.
 260  * @param new_sock The new socket that has been set up.
 261  * @param family The address family of the socket (e.g., APR_INET).
 262  * @param type The type of the socket (e.g., SOCK_STREAM).
 263  * @param cont The pool to use
 264  */
 265 APR_DECLARE(apr_status_t) apr_socket_create(apr_socket_t **new_sock,
 266                                             int family, int type,
 267                                             apr_pool_t *cont);
 268
 269 /**
 270  * Create a socket.
 271  * @remark With APR 1.0, this function is deprecated and apr_socket_create
 272  * follows this prototype.
 273  * @param new_sock The new socket that has been set up.
 274  * @param family The address family of the socket (e.g., APR_INET).
 275  * @param type The type of the socket (e.g., SOCK_STREAM).
 276  * @param protocol The protocol of the socket (e.g., APR_PROTO_TCP).
 277  * @param cont The pool to use
 278  */
 279 APR_DECLARE(apr_status_t) apr_socket_create_ex(apr_socket_t **new_sock,
 280                                                int family, int type,
 281                                                int protocol,
 282                                                apr_pool_t *cont);
 283
 284 /**
 285  * Shutdown either reading, writing, or both sides of a socket.
 286  * @param thesocket The socket to close
 287  * @param how How to shutdown the socket.  One of:
 288  * <PRE>
 289  *            APR_SHUTDOWN_READ         no longer allow read requests
 290  *            APR_SHUTDOWN_WRITE        no longer allow write requests
 291  *            APR_SHUTDOWN_READWRITE    no longer allow read or write requests
 292  * </PRE>
 293  * @see apr_shutdown_how_e
 294  * @remark This does not actually close the socket descriptor, it just
 295  *      controls which calls are still valid on the socket.
 296  */
 297 APR_DECLARE(apr_status_t) apr_socket_shutdown(apr_socket_t *thesocket,
 298                                               apr_shutdown_how_e how);
 299
 300 /** @deprecated @see apr_socket_shutdown */
 301 APR_DECLARE(apr_status_t) apr_shutdown(apr_socket_t *thesocket,
 302                                        apr_shutdown_how_e how);
 303
 304 /**
 305  * Close a socket.
 306  * @param thesocket The socket to close
 307  */
 308 APR_DECLARE(apr_status_t) apr_socket_close(apr_socket_t *thesocket);
 309
 310 /**
 311  * Bind the socket to its associated port
 312  * @param sock The socket to bind
 313  * @param sa The socket address to bind to
 314  * @remark This may be where we will find out if there is any other process
 315  *      using the selected port.
 316  */
 317 APR_DECLARE(apr_status_t) apr_socket_bind(apr_socket_t *sock,
 318                                           apr_sockaddr_t *sa);
 319
 320 /** @deprecated @see apr_socket_bind */
 321 APR_DECLARE(apr_status_t) apr_bind(apr_socket_t *sock, apr_sockaddr_t *sa);
 322
 323 /**
 324  * Listen to a bound socket for connections.
 325  * @param sock The socket to listen on
 326  * @param backlog The number of outstanding connections allowed in the sockets
 327  *                listen queue.  If this value is less than zero, the listen
 328  *                queue size is set to zero.
 329  */
 330 APR_DECLARE(apr_status_t) apr_socket_listen(apr_socket_t *sock,
 331                                             apr_int32_t backlog);
 332
 333 /** @deprecated @see apr_socket_listen */
 334 APR_DECLARE(apr_status_t) apr_listen(apr_socket_t *sock, apr_int32_t backlog);
 335
 336 /**
 337  * Accept a new connection request
 338  * @param new_sock A copy of the socket that is connected to the socket that
 339  *                 made the connection request.  This is the socket which should
 340  *                 be used for all future communication.
 341  * @param sock The socket we are listening on.
 342  * @param connection_pool The pool for the new socket.
 343  */
 344 APR_DECLARE(apr_status_t) apr_socket_accept(apr_socket_t **new_sock,
 345                                             apr_socket_t *sock,
 346                                             apr_pool_t *connection_pool);
 347
 348 /** @deprecated @see apr_socket_accept */
 349 APR_DECLARE(apr_status_t) apr_accept(apr_socket_t **new_sock,
 350                                      apr_socket_t *sock,
 351                                      apr_pool_t *connection_pool);
 352
 353 /**
 354  * Issue a connection request to a socket either on the same machine
 355  * or a different one.
 356  * @param sock The socket we wish to use for our side of the connection
 357  * @param sa The address of the machine we wish to connect to.  If NULL,
 358  *           APR assumes that the sockaddr_in in the apr_socket is
 359  *           completely filled out.
 360  */
 361 APR_DECLARE(apr_status_t) apr_socket_connect(apr_socket_t *sock,
 362                                              apr_sockaddr_t *sa);
 363
 364 /** @deprecated @see apr_socket_connect */
 365 APR_DECLARE(apr_status_t) apr_connect(apr_socket_t *sock, apr_sockaddr_t *sa);
 366
 367 /**
 368  * Create apr_sockaddr_t from hostname, address family, and port.
 369  * @param sa The new apr_sockaddr_t.
 370  * @param hostname The hostname or numeric address string to resolve/parse, or
 371  *               NULL to build an address that corresponds to 0.0.0.0 or ::
 372  * @param family The address family to use, or APR_UNSPEC if the system should
 373  *               decide.
 374  * @param port The port number.
 375  * @param flags Special processing flags:
 376  * <PRE>
 377  *       APR_IPV4_ADDR_OK          first query for IPv4 addresses; only look
 378  *                                 for IPv6 addresses if the first query failed;
 379  *                                 only valid if family is APR_UNSPEC and hostname
 380  *                                 isn't NULL; mutually exclusive with
 381  *                                 APR_IPV6_ADDR_OK
 382  *       APR_IPV6_ADDR_OK          first query for IPv6 addresses; only look
 383  *                                 for IPv4 addresses if the first query failed;
 384  *                                 only valid if family is APR_UNSPEC and hostname
 385  *                                 isn't NULL and APR_HAVE_IPV6; mutually exclusive
 386  *                                 with APR_IPV4_ADDR_OK
 387  * </PRE>
 388  * @param p The pool for the apr_sockaddr_t and associated storage.
 389  */
 390 APR_DECLARE(apr_status_t) apr_sockaddr_info_get(apr_sockaddr_t **sa,
 391                                           const char *hostname,
 392                                           apr_int32_t family,
 393                                           apr_port_t port,
 394                                           apr_int32_t flags,
 395                                           apr_pool_t *p);
 396
 397 /**
 398  * Look up the host name from an apr_sockaddr_t.
 399  * @param hostname The hostname.
 400  * @param sa The apr_sockaddr_t.
 401  * @param flags Special processing flags.
 402  */
 403 APR_DECLARE(apr_status_t) apr_getnameinfo(char **hostname,
 404                                           apr_sockaddr_t *sa,
 405                                           apr_int32_t flags);
 406
 407 /**
 408  * Parse hostname/IP address with scope id and port.
 409  *
 410  * Any of the following strings are accepted:
 411  *   8080                  (just the port number)
 412  *   www.apache.org        (just the hostname)
 413  *   www.apache.org:8080   (hostname and port number)
 414  *   [fe80::1]:80          (IPv6 numeric address string only)
 415  *   [fe80::1%eth0]        (IPv6 numeric address string and scope id)
 416  *
 417  * Invalid strings:
 418  *                         (empty string)
 419  *   [abc]                 (not valid IPv6 numeric address string)
 420  *   abc:65536             (invalid port number)
 421  *
 422  * @param addr The new buffer containing just the hostname.  On output, *addr
 423  *             will be NULL if no hostname/IP address was specfied.
 424  * @param scope_id The new buffer containing just the scope id.  On output,
 425  *                 *scope_id will be NULL if no scope id was specified.
 426  * @param port The port number.  On output, *port will be 0 if no port was
 427  *             specified.
 428  *             ### FIXME: 0 is a legal port (per RFC 1700). this should
 429  *             ### return something besides zero if the port is missing.
 430  * @param str The input string to be parsed.
 431  * @param p The pool from which *addr and *scope_id are allocated.
 432  * @remark If scope id shouldn't be allowed, check for scope_id != NULL in
 433  *         addition to checking the return code.  If addr/hostname should be
 434  *         required, check for addr == NULL in addition to checking the
 435  *         return code.
 436  */
 437 APR_DECLARE(apr_status_t) apr_parse_addr_port(char **addr,
 438                                               char **scope_id,
 439                                               apr_port_t *port,
 440                                               const char *str,
 441                                               apr_pool_t *p);
 442
 443 /**
 444  * Get name of the current machine
 445  * @param buf A buffer to store the hostname in.
 446  * @param len The maximum length of the hostname that can be stored in the
 447  *            buffer provided.  The suggested length is APRMAXHOSTLEN + 1.
 448  * @param cont The pool to use.
 449  * @remark If the buffer was not large enough, an error will be returned.
 450  */
 451 APR_DECLARE(apr_status_t) apr_gethostname(char *buf, int len, apr_pool_t *cont);
 452
 453 /**
 454  * Return the data associated with the current socket
 455  * @param data The user data associated with the socket.
 456  * @param key The key to associate with the user data.
 457  * @param sock The currently open socket.
 458  */
 459 APR_DECLARE(apr_status_t) apr_socket_data_get(void **data, const char *key,
 460                                               apr_socket_t *sock);
 461
 462 /**
 463  * Set the data associated with the current socket.
 464  * @param sock The currently open socket.
 465  * @param data The user data to associate with the socket.
 466  * @param key The key to associate with the data.
 467  * @param cleanup The cleanup to call when the socket is destroyed.
 468  */
 469 APR_DECLARE(apr_status_t) apr_socket_data_set(apr_socket_t *sock, void *data,
 470                                               const char *key,
 471                                               apr_status_t (*cleanup)(void*));
 472
 473 /**
 474  * Send data over a network.
 475  * @param sock The socket to send the data over.
 476  * @param buf The buffer which contains the data to be sent.
 477  * @param len On entry, the number of bytes to send; on exit, the number
 478  *            of bytes sent.
 479  * @remark
 480  * <PRE>
 481  * This functions acts like a blocking write by default.  To change
 482  * this behavior, use apr_socket_timeout_set().
 483  *
 484  * It is possible for both bytes to be sent and an error to be returned.
 485  *
 486  * APR_EINTR is never returned.
 487  * </PRE>
 488  */
 489 APR_DECLARE(apr_status_t) apr_socket_send(apr_socket_t *sock, const char *buf,
 490                                           apr_size_t *len);
 491
 492 /** @deprecated @see apr_socket_send */
 493 APR_DECLARE(apr_status_t) apr_send(apr_socket_t *sock, const char *buf,
 494                                    apr_size_t *len);
 495
 496 /**
 497  * Send multiple packets of data over a network.
 498  * @param sock The socket to send the data over.
 499  * @param vec The array of iovec structs containing the data to send
 500  * @param nvec The number of iovec structs in the array
 501  * @param len Receives the number of bytes actually written
 502  * @remark
 503  * <PRE>
 504  * This functions acts like a blocking write by default.  To change
 505  * this behavior, use apr_socket_timeout_set().
 506  * The number of bytes actually sent is stored in argument 3.
 507  *
 508  * It is possible for both bytes to be sent and an error to be returned.
 509  *
 510  * APR_EINTR is never returned.
 511  * </PRE>
 512  */
 513 APR_DECLARE(apr_status_t) apr_socket_sendv(apr_socket_t *sock,
 514                                            const struct iovec *vec,
 515                                            apr_int32_t nvec, apr_size_t *len);
 516
 517 /** @deprecated @see apr_socket_sendv */
 518 APR_DECLARE(apr_status_t) apr_sendv(apr_socket_t *sock,
 519                                     const struct iovec *vec,
 520                                     apr_int32_t nvec, apr_size_t *len);
 521
 522 /**
 523  * @param sock The socket to send from
 524  * @param where The apr_sockaddr_t describing where to send the data
 525  * @param flags The flags to use
 526  * @param buf  The data to send
 527  * @param len  The length of the data to send
 528  */
 529 APR_DECLARE(apr_status_t) apr_socket_sendto(apr_socket_t *sock,
 530                                             apr_sockaddr_t *where,
 531                                             apr_int32_t flags, const char *buf,
 532                                             apr_size_t *len);
 533
 534 /** @deprecated @see apr_socket_sendto */
 535 APR_DECLARE(apr_status_t) apr_sendto(apr_socket_t *sock, apr_sockaddr_t *where,
 536                                      apr_int32_t flags, const char *buf,
 537                                      apr_size_t *len);
 538
 539 /**
 540  * @param from The apr_sockaddr_t to fill in the recipient info
 541  * @param sock The socket to use
 542  * @param flags The flags to use
 543  * @param buf  The buffer to use
 544  * @param len  The length of the available buffer
 545  */
 546
 547 APR_DECLARE(apr_status_t) apr_socket_recvfrom(apr_sockaddr_t *from,
 548                                               apr_socket_t *sock,
 549                                               apr_int32_t flags, char *buf,
 550                                               apr_size_t *len);
 551
 552 /** @deprecated @see apr_socket_recvfrom */
 553 APR_DECLARE(apr_status_t) apr_recvfrom(apr_sockaddr_t *from, apr_socket_t *sock,
 554                                        apr_int32_t flags, char *buf,
 555                                        apr_size_t *len);
 556
 557 #if APR_HAS_SENDFILE || defined(DOXYGEN)
 558
 559 /**
 560  * Send a file from an open file descriptor to a socket, along with
 561  * optional headers and trailers
 562  * @param sock The socket to which we're writing
 563  * @param file The open file from which to read
 564  * @param hdtr A structure containing the headers and trailers to send
 565  * @param offset Offset into the file where we should begin writing
 566  * @param len (input)  - Number of bytes to send from the file
 567  *            (output) - Number of bytes actually sent,
 568  *                       including headers, file, and trailers
 569  * @param flags APR flags that are mapped to OS specific flags
 570  * @remark This functions acts like a blocking write by default.  To change
 571  *         this behavior, use apr_socket_timeout_set().
 572  *         The number of bytes actually sent is stored in argument 5.
 573  */
 574 APR_DECLARE(apr_status_t) apr_socket_sendfile(apr_socket_t *sock,
 575                                               apr_file_t *file,
 576                                               apr_hdtr_t *hdtr,
 577                                               apr_off_t *offset,
 578                                               apr_size_t *len,
 579                                               apr_int32_t flags);
 580
 581 /** @deprecated @see apr_socket_sendfile */
 582 APR_DECLARE(apr_status_t) apr_sendfile(apr_socket_t *sock, apr_file_t *file,
 583                                        apr_hdtr_t *hdtr, apr_off_t *offset,
 584                                        apr_size_t *len, apr_int32_t flags);
 585
 586 #endif /* APR_HAS_SENDFILE */
 587
 588 /**
 589  * Read data from a network.
 590  * @param sock The socket to read the data from.
 591  * @param buf The buffer to store the data in.
 592  * @param len On entry, the number of bytes to receive; on exit, the number
 593  *            of bytes received.
 594  * @remark
 595  * <PRE>
 596  * This functions acts like a blocking read by default.  To change
 597  * this behavior, use apr_socket_timeout_set().
 598  * The number of bytes actually sent is stored in argument 3.
 599  *
 600  * It is possible for both bytes to be received and an APR_EOF or
 601  * other error to be returned.
 602  *
 603  * APR_EINTR is never returned.
 604  * </PRE>
 605  */
 606 APR_DECLARE(apr_status_t) apr_socket_recv(apr_socket_t *sock,
 607                                    char *buf, apr_size_t *len);
 608
 609 /** @deprecated @see apr_socket_recv */
 610 APR_DECLARE(apr_status_t) apr_recv(apr_socket_t *sock,
 611                                    char *buf, apr_size_t *len);
 612
 613 /**
 614  * Setup socket options for the specified socket
 615  * @param sock The socket to set up.
 616  * @param opt The option we would like to configure.  One of:
 617  * <PRE>
 618  *            APR_SO_DEBUG      --  turn on debugging information
 619  *            APR_SO_KEEPALIVE  --  keep connections active
 620  *            APR_SO_LINGER     --  lingers on close if data is present
 621  *            APR_SO_NONBLOCK   --  Turns blocking on/off for socket
 622  *            APR_SO_REUSEADDR  --  The rules used in validating addresses
 623  *                                  supplied to bind should allow reuse
 624  *                                  of local addresses.
 625  *            APR_SO_SNDBUF     --  Set the SendBufferSize
 626  *            APR_SO_RCVBUF     --  Set the ReceiveBufferSize
 627  * </PRE>
 628  * @param on Value for the option.
 629  */
 630 APR_DECLARE(apr_status_t) apr_socket_opt_set(apr_socket_t *sock,
 631                                              apr_int32_t opt, apr_int32_t on);
 632
 633 /** @deprecated @see apr_socket_opt_set */
 634 APR_DECLARE(apr_status_t) apr_setsocketopt(apr_socket_t *sock,
 635                                            apr_int32_t opt, apr_int32_t on);
 636
 637 /**
 638  * Setup socket timeout for the specified socket
 639  * @param sock The socket to set up.
 640  * @param t Value for the timeout.
 641  * <PRE>
 642  *   t > 0  -- read and write calls return APR_TIMEUP if specified time
 643  *             elapsess with no data read or written
 644  *   t == 0 -- read and write calls never block
 645  *   t < 0  -- read and write calls block
 646  * </PRE>
 647  */
 648 APR_DECLARE(apr_status_t) apr_socket_timeout_set(apr_socket_t *sock,
 649                                                  apr_interval_time_t t);
 650
 651 /**
 652  * Query socket options for the specified socket
 653  * @param sock The socket to query
 654  * @param opt The option we would like to query.  One of:
 655  * <PRE>
 656  *            APR_SO_DEBUG      --  turn on debugging information
 657  *            APR_SO_KEEPALIVE  --  keep connections active
 658  *            APR_SO_LINGER     --  lingers on close if data is present
 659  *            APR_SO_NONBLOCK   --  Turns blocking on/off for socket
 660  *            APR_SO_REUSEADDR  --  The rules used in validating addresses
 661  *                                  supplied to bind should allow reuse
 662  *                                  of local addresses.
 663  *            APR_SO_SNDBUF     --  Set the SendBufferSize
 664  *            APR_SO_RCVBUF     --  Set the ReceiveBufferSize
 665  *            APR_SO_DISCONNECTED -- Query the disconnected state of the socket.
 666  *                                  (Currently only used on Windows)
 667  * </PRE>
 668  * @param on Socket option returned on the call.
 669  */
 670 APR_DECLARE(apr_status_t) apr_socket_opt_get(apr_socket_t *sock,
 671                                              apr_int32_t opt, apr_int32_t *on);
 672
 673 /** @deprecated @see apr_socket_opt_set */
 674 APR_DECLARE(apr_status_t) apr_getsocketopt(apr_socket_t *sock,
 675                                            apr_int32_t opt, apr_int32_t *on);
 676
 677 /**
 678  * Query socket timeout for the specified socket
 679  * @param sock The socket to query
 680  * @param t Socket timeout returned from the query.
 681  */
 682 APR_DECLARE(apr_status_t) apr_socket_timeout_get(apr_socket_t *sock,
 683                                                  apr_interval_time_t *t);
 684
 685 /**
 686  * Query the specified socket if at the OOB/Urgent data mark
 687  * @param sock The socket to query
 688  * @param atmark Is set to true if socket is at the OOB/urgent mark,
 689  *               otherwise is set to false.
 690  */
 691 APR_DECLARE(apr_status_t) apr_socket_atmark(apr_socket_t *sock,
 692                                             int *atmark);
 693
 694 /**
 695  * Return an apr_sockaddr_t from an apr_socket_t
 696  * @param sa The returned apr_sockaddr_t.
 697  * @param which Which interface do we want the apr_sockaddr_t for?
 698  * @param sock The socket to use
 699  */
 700 APR_DECLARE(apr_status_t) apr_socket_addr_get(apr_sockaddr_t **sa,
 701                                               apr_interface_e which,
 702                                               apr_socket_t *sock);
 703
 704 /**
 705  * Set the port in an APR socket address.
 706  * @param sockaddr The socket address to set.
 707  * @param port The port to be stored in the socket address.
 708  * @deprecated @see apr_sockaddr_info_get
 709  */
 710 APR_DECLARE(apr_status_t) apr_sockaddr_port_set(apr_sockaddr_t *sockaddr,
 711                                                 apr_port_t port);
 712
 713 /**
 714  * Return the port in an APR socket address.
 715  * @param port The port from the socket address.
 716  * @param sockaddr The socket address to reference.
 717  * @deprecated Access port field directly.
 718  */
 719 APR_DECLARE(apr_status_t) apr_sockaddr_port_get(apr_port_t *port,
 720                                                 apr_sockaddr_t *sockaddr);
 721
 722 /**
 723  * Set the IP address in an APR socket address.
 724  * @param sockaddr The socket address to use
 725  * @param addr The IP address to attach to the socket.
 726  *             Use APR_ANYADDR to use any IP addr on the machine.
 727  * @deprecated @see apr_sockaddr_info_get
 728  */
 729 APR_DECLARE(apr_status_t) apr_sockaddr_ip_set(apr_sockaddr_t *sockaddr,
 730                                               const char *addr);
 731
 732 /**
 733  * Return the IP address (in numeric address string format) in
 734  * an APR socket address.  APR will allocate storage for the IP address
 735  * string from the pool of the apr_sockaddr_t.
 736  * @param addr The IP address.
 737  * @param sockaddr The socket address to reference.
 738  */
 739 APR_DECLARE(apr_status_t) apr_sockaddr_ip_get(char **addr,
 740                                               apr_sockaddr_t *sockaddr);
 741
 742 /**
 743  * See if the IP addresses in two APR socket addresses are
 744  * equivalent.  Appropriate logic is present for comparing
 745  * IPv4-mapped IPv6 addresses with IPv4 addresses.
 746  *
 747  * @param addr1 One of the APR socket addresses.
 748  * @param addr2 The other APR socket address.
 749  * @remark The return value will be non-zero if the addresses
 750  * are equivalent.
 751  */
 752 APR_DECLARE(int) apr_sockaddr_equal(const apr_sockaddr_t *addr1,
 753                                     const apr_sockaddr_t *addr2);
 754
 755
 756 #if APR_FILES_AS_SOCKETS || defined(DOXYGEN)
 757
 758 /**
 759  * Convert a File type to a socket so that it can be used in a poll operation.
 760  * @param newsock the newly created socket which represents a file.
 761  * @param file the file to mask as a socket.
 762  * @warning This is not available on all platforms.  Platforms that have the
 763  *      ability to poll files for data to be read/written/exceptions will
 764  *      have the APR_FILES_AS_SOCKETS macro defined as true.
 765  * @deprecated This function has been deprecated, because of the new poll
 766  *             implementation.
 767  */
 768 APR_DECLARE(apr_status_t) apr_socket_from_file(apr_socket_t **newsock,
 769                                                apr_file_t *file);
 770
 771 #endif /* APR_FILES_AS_SOCKETS */
 772
 773 /**
 774  * Given an apr_sockaddr_t and a service name, set the port for the service
 775  * @param sockaddr The apr_sockaddr_t that will have its port set
 776  * @param servname The name of the service you wish to use
 777  */
 778 APR_DECLARE(apr_status_t) apr_getservbyname(apr_sockaddr_t *sockaddr,
 779                                             const char *servname);
 780 /**
 781  * Build an ip-subnet representation from an IP address and optional netmask or
 782  * number-of-bits.
 783  * @param ipsub The new ip-subnet representation
 784  * @param ipstr The input IP address string
 785  * @param mask_or_numbits The input netmask or number-of-bits string, or NULL
 786  * @param p The pool to allocate from
 787  */
 788 APR_DECLARE(apr_status_t) apr_ipsubnet_create(apr_ipsubnet_t **ipsub,
 789                                               const char *ipstr,
 790                                               const char *mask_or_numbits,
 791                                               apr_pool_t *p);
 792
 793 /**
 794  * Test the IP address in an apr_sockaddr_t against a pre-built ip-subnet
 795  * representation.
 796  * @param ipsub The ip-subnet representation
 797  * @param sa The socket address to test
 798  * @return non-zero if the socket address is within the subnet, 0 otherwise
 799  */
 800 APR_DECLARE(int) apr_ipsubnet_test(apr_ipsubnet_t *ipsub, apr_sockaddr_t *sa);
 801
 802 #if APR_HAS_SO_ACCEPTFILTER || defined(DOXYGEN)
 803 /**
 804  * Set an OS level accept filter.
 805  * @param sock The socket to put the accept filter on.
 806  * @param name The accept filter
 807  * @param args Any extra args to the accept filter.  Passing NULL here removes
 808  *             the accept filter.
 809  */
 810 apr_status_t apr_socket_accept_filter(apr_socket_t *sock, char *name,
 811                                       char *args);
 812 #endif
 813
 814 /**
 815  * Return the protocol of the socket.
 816  * @param sock The socket to query.
 817  * @param protocol The returned protocol (e.g., APR_PROTO_TCP).
 818  */
 819 APR_DECLARE(apr_status_t) apr_socket_protocol_get(apr_socket_t *sock,
 820                                                   int *protocol);
 821
 822 /**
 823  * Set a socket to be inherited by child processes.
 824  */
 825 APR_DECLARE_INHERIT_SET(socket);
 826
 827 /** @deprecated @see apr_socket_inherit_set */
 828 APR_DECLARE(void) apr_socket_set_inherit(apr_socket_t *skt);
 829
 830 /**
 831  * Unset a socket from being inherited by child processes.
 832  */
 833 APR_DECLARE_INHERIT_UNSET(socket);
 834
 835 /** @deprecated @see apr_socket_inherit_unset */
 836 APR_DECLARE(void) apr_socket_unset_inherit(apr_socket_t *skt);
 837
 838 /** @} */
 839
 840 #ifdef __cplusplus
 841 }
 842 #endif
 843
 844 #endif  /* ! APR_NETWORK_IO_H */
 845