rbb 99/07/29 12:23:31
Modified: apr/file_io/unix dir.c pipe.c
apr/network_io/unix poll.c sendrecv.c sockets.c
Log:
More docs changes.
Revision Changes Path
1.18 +1 -0 apache-apr/apr/file_io/unix/dir.c
Index: dir.c
===================================================================
RCS file: /home/cvs/apache-apr/apr/file_io/unix/dir.c,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- dir.c 1999/07/27 19:26:12 1.17
+++ dir.c 1999/07/29 19:23:14 1.18
@@ -73,6 +73,7 @@
return errno;
}
}
+
/* ***APRDOC********************************************************
* ap_status_t ap_opendir(ap_context_t *, char *, ap_dir_t **)
* Open the specified directory.
1.13 +3 -3 apache-apr/apr/file_io/unix/pipe.c
Index: pipe.c
===================================================================
RCS file: /home/cvs/apache-apr/apr/file_io/unix/pipe.c,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- pipe.c 1999/07/28 18:10:58 1.12
+++ pipe.c 1999/07/29 19:23:16 1.13
@@ -65,7 +65,7 @@
/* ***APRDOC********************************************************
* ap_status_t ap_create_pipe(ap_context_t *, ap_file_t **, ap_file_t **)
- * Create an anonymous pipt.
+ * Create an anonymous pipe.
* arg 1) The context to operate on.
* arg 2) The file descriptor to use as input to the pipe.
* arg 3) The file descriptor to use as output from the pipe.
@@ -94,9 +94,9 @@
/* ***APRDOC********************************************************
* ap_status_t ap_create_namedpipe(ap_context_t *, char *, ap_fileperms_t,
* char **)
- * Create a named pipt.
+ * Create a named pipe.
* arg 1) The context to operate on.
- * arg 2) The The directory to create the pipe in.
+ * arg 2) The directory to create the pipe in.
* arg 3) The permissions for the newly created pipe.
* arg 4) The name of the new pipe.
*/
1.15 +43 -1 apache-apr/apr/network_io/unix/poll.c
Index: poll.c
===================================================================
RCS file: /home/cvs/apache-apr/apr/network_io/unix/poll.c,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- poll.c 1999/06/22 16:57:30 1.14
+++ poll.c 1999/07/29 19:23:25 1.15
@@ -62,6 +62,13 @@
#ifdef HAVE_POLL /* We can just use poll to do our socket polling. */
+/* ***APRDOC********************************************************
+ * ap_status_t ap_setup_poll(ap_context_t *, ap_int32_t, ap_pollfd_t **)
+ * Setup the memory required for poll to operate properly.
+ * arg 1) The context to operate on.
+ * arg 2) The number of socket descriptors to be polled.
+ * arg 3) The poll structure to be used.
+ */
ap_status_t ap_setup_poll(ap_context_t *cont, ap_int32_t num, struct
pollfd_t **new)
{
(*new) = (struct pollfd_t *)ap_palloc(cont, sizeof(struct pollfd_t) *
num);
@@ -113,6 +120,16 @@
return rv;
}
+/* ***APRDOC********************************************************
+ * ap_status_t ap_add_poll_socket(ap_pollfd_t *, ap_socket_t *, ap_int16_t)
+ * Add a socket to the poll structure.
+ * arg 1) The poll structure we will be using.
+ * arg 2) The socket to add to the current poll structure.
+ * arg 3) The events to look for when we do the poll. One of:
+ * APR_POLLIN -- signal if read will not block
+ * APR_POLLPRI -- signal if prioirty data is availble to be read
+ * APR_POLLOUT -- signal if write will not block
+ */
ap_status_t ap_add_poll_socket(struct pollfd_t *aprset,
struct socket_t *sock, ap_int16_t event)
{
@@ -130,6 +147,18 @@
return APR_SUCCESS;
}
+/* ***APRDOC********************************************************
+ * ap_status_t ap_poll(ap_pollfd_t *, ap_int32_t *, ap_int32_t)
+ * Poll the sockets in the poll structure. This is a blocking call,
+ * and it will not return until either a socket has been signalled, or
+ * the timeout has expired.
+ * arg 1) The poll structure we will be using.
+ * arg 2) The number of sockets we are polling.
+ * arg 3) The amount of time in seconds to wait. This is a maximum, not
+ * a minimum. If a socket is signalled, we will wake up before this
+ * time. A negative number means wait until a socket is signalled.
+ * NOTE: The number of sockets signalled is returned in the second
argument.
+ */
ap_status_t ap_poll(struct pollfd_t *aprset, ap_int32_t *nsds, ap_int32_t
timeout)
{
int i;
@@ -161,6 +190,20 @@
return APR_SUCCESS;
}
+/* ***APRDOC********************************************************
+ * ap_status_t ap_get_revents(ap_pollfd_t *, ap_socket_t *, ap_int_16_t *)
+ * Get the return events for the specified socket.
+ * arg 1) The poll structure we will be using.
+ * arg 2) The socket we wish to get information about.
+ * arg 3) The returned events for the socket. One of:
+ * APR_POLLIN -- Data is available to be read
+ * APR_POLLPRI -- Prioirty data is availble to be read
+ * APR_POLLOUT -- Write will succeed
+ * APR_POLLERR -- An error occurred on the socket
+ * APR_POLLHUP -- The connection has been terminated
+ * APR_POLLNVAL -- This is an invalid socket to poll on.
+ * Socket not open.
+ */
ap_status_t ap_get_revents(struct pollfd_t *aprset, struct socket_t *sock,
ap_int16_t *event)
{
int i = 0;
@@ -325,5 +368,4 @@
return APR_ENOFILE;
}
}
-
1.11 +24 -0 apache-apr/apr/network_io/unix/sendrecv.c
Index: sendrecv.c
===================================================================
RCS file: /home/cvs/apache-apr/apr/network_io/unix/sendrecv.c,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- sendrecv.c 1999/06/09 15:55:55 1.10
+++ sendrecv.c 1999/07/29 19:23:25 1.11
@@ -61,6 +61,18 @@
#include "apr_network_io.h"
#include <sys/time.h>
+/* ***APRDOC********************************************************
+ * ap_status_t ap_send(ap_socket_t *, const char *, ap_ssize_t *, time_t)
+ * Send data over a network.
+ * arg 1) The socket to send the data over.
+ * arg 2) The buffer which contains the data to be sent.
+ * arg 3) The maximum number of bytes to send
+ * arg 4) The amount of time in seconds to try sending this data.
+ * NOTE: The number of bytes actually sent is stored in argument 3. It is
+ * not currently possible to have this behave like a blocking write.
+ * If the timeout is zero, it will try to send the data, and return
+ * immediately.
+ */
ap_status_t ap_send(struct socket_t *sock, const char *buf, ap_ssize_t *len,
time_t sec)
{
ssize_t rv;
@@ -101,6 +113,18 @@
return APR_SUCCESS;
}
+/* ***APRDOC********************************************************
+ * ap_status_t ap_recv(ap_socket_t *, char *, ap_ssize_t *, time_t)
+ * Read data from a network.
+ * arg 1) The socket to read the data from.
+ * arg 2) The buffer to store the data in.
+ * arg 3) The maximum number of bytes to read
+ * arg 4) The amount of time in seconds to try reading data.
+ * NOTE: The number of bytes actually read is stored in argument 3. It is
+ * not currently possible to have this behave like a blocking read.
+ * If the timeout is zero, it will try to read data, and return
+ * immediately.
+ */
ap_status_t ap_recv(struct socket_t *sock, char *buf, ap_ssize_t *len,
time_t sec)
{
ssize_t rv;
1.23 +75 -1 apache-apr/apr/network_io/unix/sockets.c
Index: sockets.c
===================================================================
RCS file: /home/cvs/apache-apr/apr/network_io/unix/sockets.c,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -r1.22 -r1.23
--- sockets.c 1999/07/06 17:01:40 1.22
+++ sockets.c 1999/07/29 19:23:27 1.23
@@ -77,6 +77,12 @@
}
}
+/* ***APRDOC********************************************************
+ * ap_status_t ap_create_tcp_socket(ap_context_t *, ap_socket_t **)
+ * Create a socket for tcp communication.
+ * arg 1) The context to use
+ * arg 2) The new socket that has been setup.
+ */
ap_status_t ap_create_tcp_socket(ap_context_t *cont, struct socket_t **new)
{
(*new) = (struct socket_t *)ap_palloc(cont, sizeof(struct socket_t));
@@ -107,6 +113,17 @@
return APR_SUCCESS;
}
+/* ***APRDOC********************************************************
+ * ap_status_t ap_shutdown(ap_socket_t *, ap_shutdown_how_e)
+ * Shutdown either reading, writing, or both sides of a tcp socket.
+ * arg 1) The socket to close
+ * arg 2) 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
+ * NOTE: This does not actually close the socket descriptor, it just
+ * controls which calls are still valid on the socket.
+ */
ap_status_t ap_shutdown(struct socket_t *thesocket, ap_shutdown_how_e how)
{
if (shutdown(thesocket->socketdes, how) == 0) {
@@ -117,18 +134,39 @@
}
}
+/* ***APRDOC********************************************************
+ * ap_status_t ap_close_socket(ap_socket_t *)
+ * Close a tcp socket.
+ * arg 1) The socket to close
+ */
ap_status_t ap_close_socket(struct socket_t *thesocket)
{
ap_kill_cleanup(thesocket->cntxt, thesocket, socket_cleanup);
return socket_cleanup(thesocket);
}
+/* ***APRDOC********************************************************
+ * ap_status_t ap_setport(ap_socket_t *, ap_uint32_t)
+ * Assocaite a port with a socket.
+ * arg 1) The socket use
+ * arg 2) The port this socket will be dealing with.
+ * NOTE: This does not bind the two together, it is just telling apr
+ * that this socket is going to use this port if possible. If
+ * the port is already used, we won't find out about it here.
+ */
ap_status_t ap_setport(struct socket_t *sock, ap_uint32_t port)
{
sock->addr->sin_port = htons((short)port);
return APR_SUCCESS;
}
+/* ***APRDOC********************************************************
+ * ap_status_t ap_bind(ap_socket_t *)
+ * Bind the socket to it's assocaited port
+ * arg 1) The socket to bind
+ * NOTE: This is where we will find out if there is any other process
+ * using the selected port.
+ */
ap_status_t ap_bind(struct socket_t *sock)
{
sock->addr->sin_addr.s_addr = INADDR_ANY;
@@ -138,6 +176,14 @@
return APR_SUCCESS;
}
+/* ***APRDOC********************************************************
+ * ap_status_t ap_listen(ap_socket_t *, ap_int32_t)
+ * Listen to a bound socketi for connections.
+ * arg 1) The socket to listen on
+ * arg 2) 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.
+ */
ap_status_t ap_listen(struct socket_t *sock, ap_int32_t backlog)
{
if (listen(sock->socketdes, backlog) == -1)
@@ -146,6 +192,14 @@
return APR_SUCCESS;
}
+/* ***APRDOC********************************************************
+ * ap_status_t ap_accept(ap_socket_t *, ap_socket_t **)
+ * Accept a new connection request
+ * arg 1) The socket we are listening on
+ * arg 2) 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.
+ */
ap_status_t ap_accept(const struct socket_t *sock, struct socket_t **new)
{
struct hostent *hptr;
@@ -176,6 +230,13 @@
return APR_SUCCESS;
}
+/* ***APRDOC********************************************************
+ * ap_status_t ap_connect(ap_socket_t *, char *)
+ * Issue a connection request to a socket either on the same machine
+ * or a different one.
+ * arg 1) The socket we wish to use for our side of the connection
+ * arg 2) The hostname of the machine we wish to connect to.
+ */
ap_status_t ap_connect(struct socket_t *sock, char *hostname)
{
struct hostent *hp;
@@ -227,7 +288,7 @@
/* ***APRDOC********************************************************
* ap_status_t ap_set_socketdata(ap_socket_t *, void *)
- * Return the context associated with the current socket.
+ * Set the context associated with the current socket.
* arg 1) The currently open socket.
* arg 2) The user data to associate with the socket.
*/
@@ -242,6 +303,12 @@
}
}
+/* ***APRDOC********************************************************
+ * ap_status_t ap_get_os_sock(ap_socket_t *, ap_os_sock_t *)
+ * Convert the socket from an apr type to an OS specific socket
+ * arg 1) The socket to convert.
+ * arg 2) The os specifc equivelant of the apr socket..
+ */
ap_status_t ap_get_os_sock(struct socket_t *sock, ap_os_sock_t *thesock)
{
if (sock == NULL) {
@@ -251,6 +318,13 @@
return APR_SUCCESS;
}
+/* ***APRDOC********************************************************
+ * ap_status_t ap_put_os_sock(ap_context_t *, ap_socket_t **, ap_os_socket_t
*)
+ * Convert a socket from the os specific type to the apr type
+ * arg 1) The context to use.
+ * arg 2) The socket to convert to.
+ * arg 3) The socket we are converting to an apr type.
+ */
ap_status_t ap_put_os_sock(ap_context_t *cont, struct socket_t **sock,
ap_os_sock_t *thesock)
{
