third batch of perlpod(1) to mdoc(7) conversion

1 files changed, 279 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/BIO_s_accept.3 b/src/lib/libcrypto/man/BIO_s_accept.3
new file mode 100644
index 0000000000..f5adfcc07c
--- /dev/null
+++ b/src/lib/libcrypto/man/BIO_s_accept.3
@@ -0,0 +1,279 @@
+.Dd $Mdocdate: February 16 2015 $
+.Dt BIO_S_ACCEPT 3
+.Os
+.Sh NAME
+.Nm BIO_s_accept ,
+.Nm BIO_set_accept_port ,
+.Nm BIO_get_accept_port ,
+.Nm BIO_new_accept ,
+.Nm BIO_set_nbio_accept ,
+.Nm BIO_set_accept_bios ,
+.Nm BIO_set_bind_mode ,
+.Nm BIO_get_bind_mode ,
+.Nm BIO_do_accept
+.Nd accept BIO
+.Sh SYNOPSIS
+.In openssl/bio.h
+.Ft BIO_METHOD *
+.Fo BIO_s_accept
+.Fa void
+.Fc
+.Ft long
+.Fo BIO_set_accept_port
+.Fa "BIO *b"
+.Fa "char *name"
+.Fc
+.Ft char *
+.Fo BIO_get_accept_port
+.Fa "BIO *b"
+.Fc
+.Ft BIO *
+.Fo BIO_new_accept
+.Fa "char *host_port"
+.Fc
+.Ft long
+.Fo BIO_set_nbio_accept
+.Fa "BIO *b"
+.Fa "int n"
+.Fc
+.Ft long
+.Fo BIO_set_accept_bios
+.Fa "BIO *b"
+.Fa "char *bio"
+.Fc
+.Ft long
+.Fo BIO_set_bind_mode
+.Fa "BIO *b"
+.Fa "long mode"
+.Fc
+.Ft long
+.Fo BIO_get_bind_mode
+.Fa "BIO *b"
+.Fa "long dummy"
+.Fc
+.Fd #define BIO_BIND_NORMAL                             0
+.Fd #define BIO_BIND_REUSEADDR_IF_UNUSED        1
+.Fd #define BIO_BIND_REUSEADDR                  2
+.Ft int
+.Fo BIO_do_accept
+.Fa "BIO *b"
+.Fc
+.Sh DESCRIPTION
+.Fn BIO_s_accept
+returns the accept BIO method.
+This is a wrapper round the platform's TCP/IP socket accept routines.
+.Pp
+Using accept BIOs, TCP/IP connections can be accepted
+and data transferred using only BIO routines.
+In this way any platform specific operations
+are hidden by the BIO abstraction.
+.Pp
+Read and write operations on an accept BIO
+will perform I/O on the underlying connection.
+If no connection is established and the port (see below) is set up
+properly then the BIO waits for an incoming connection.
+.Pp
+Accept BIOs support
+.Xr BIO_puts 3
+but not
+.Xr BIO_gets 3 .
+.Pp
+If the close flag is set on an accept BIO, then any active
+connection on that chain is shutdown and the socket closed when
+the BIO is freed.
+.Pp
+Calling
+.Xr BIO_reset 3
+on a accept BIO will close any active connection and reset the BIO
+into a state where it awaits another incoming connection.
+.Pp
+.Xr BIO_get_fd 3
+and
+.Xr BIO_set_fd 3
+can be called to retrieve or set the accept socket.
+See
+.Xr BIO_s_fd 3 .
+.Pp
+.Fn BIO_set_accept_port
+uses the string
+.Fa name
+to set the accept port.
+The port is represented as a string of the form
+.Ar host : Ns Ar port ,
+where
+.Ar host
+is the interface to use and
+.Ar port
+is the port.
+Either or both values can be
+.Qq *
+which is interpreted as meaning any interface or port respectively.
+.Ar port
+has the same syntax as the port specified in
+.Xr BIO_set_conn_port 3
+for connect BIOs.
+It can be a numerical port string or a string to lookup using
+.Xr getservbyname 3
+and a string table.
+.Pp
+.Fn BIO_new_accept
+combines
+.Xr BIO_new 3
+and
+.Fn BIO_set_accept_port
+into a single call.
+It creates a new accept BIO with port
+.Fa host_port .
+.Pp
+.Fn BIO_set_nbio_accept
+sets the accept socket to blocking mode (the default) if
+.Fa n
+is 0 or non blocking mode if
+.Fa n
+is 1.
+.Pp
+.Fn BIO_set_accept_bios
+can be used to set a chain of BIOs which will be duplicated
+and prepended to the chain when an incoming connection is received.
+This is useful if, for example, a buffering or SSL BIO
+is required for each connection.
+The chain of BIOs must not be freed after this call,
+they will be automatically freed when the accept BIO is freed.
+.Pp
+.Fn BIO_set_bind_mode
+and
+.Fn BIO_get_bind_mode
+set and retrieve the current bind mode.
+If
+.Dv BIO_BIND_NORMAL Pq the default
+is set, then another socket cannot be bound to the same port.
+If
+.Dv BIO_BIND_REUSEADDR
+is set, then other sockets can bind to the same port.
+If
+.Dv BIO_BIND_REUSEADDR_IF_UNUSED
+is set, then an attempt is first made to use
+.Dv BIO_BIN_NORMAL ;
+if this fails and the port is not in use,
+then a second attempt is made using
+.Dv BIO_BIND_REUSEADDR .
+.Pp
+.Fn BIO_do_accept
+serves two purposes.
+When it is first called, after the accept BIO has been setup,
+it will attempt to create the accept socket and bind an address to it.
+Second and subsequent calls to
+.Fn BIO_do_accept
+will await an incoming connection, or request a retry in non blocking mode.
+.Sh NOTES
+When an accept BIO is at the end of a chain, it will await an
+incoming connection before processing I/O calls.
+When an accept BIO is not at then end of a chain,
+it passes I/O calls to the next BIO in the chain.
+.Pp
+When a connection is established a new socket BIO is created
+for the connection and appended to the chain.
+That is the chain is now accept->socket.
+This effectively means that attempting I/O on an initial accept
+socket will await an incoming connection then perform I/O on it.
+.Pp
+If any additional BIOs have been set using
+.Fn BIO_set_accept_bios ,
+then they are placed between the socket and the accept BIO,
+that is the chain will be accept->otherbios->socket.
+.Pp
+If a server wishes to process multiple connections (as is normally
+the case), then the accept BIO must be made available for further
+incoming connections.
+This can be done by waiting for a connection and then calling:
+.Pp
+.Dl connection = BIO_pop(accept);
+.Pp
+After this call,
+.Sy connection
+will contain a BIO for the recently established connection and
+.Sy accept
+will now be a single BIO again which can be used
+to await further incoming connections.
+If no further connections will be accepted, the
+.Sy accept
+can be freed using
+.Xr BIO_free 3 .
+.Pp
+If only a single connection will be processed,
+it is possible to perform I/O using the accept BIO itself.
+This is often undesirable however because the accept BIO
+will still accept additional incoming connections.
+This can be resolved by using
+.Xr BIO_pop 3
+(see above) and freeing up the accept BIO after the initial connection.
+.Pp
+If the underlying accept socket is non-blocking and
+.Fn BIO_do_accept
+is called to await an incoming connection, it is possible for
+.Xr BIO_should_io_special 3
+with the reason
+.Dv BIO_RR_ACCEPT .
+If this happens, then it is an indication that an accept attempt
+would block: the application should take appropriate action
+to wait until the underlying socket has accepted a connection
+and retry the call.
+.Pp
+.Fn BIO_set_accept_port ,
+.Fn BIO_get_accept_port ,
+.Fn BIO_set_nbio_accept ,
+.Fn BIO_set_accept_bios ,
+.Fn BIO_set_bind_mode ,
+.Fn BIO_get_bind_mode ,
+and
+.Fn BIO_do_accept
+are macros.
+.Sh EXAMPLES
+This example accepts two connections on port 4444,
+sends messages down each and finally closes both down.
+.Bd -literal -offset 2n
+BIO *abio, *cbio, *cbio2;
+ERR_load_crypto_strings();
+abio = BIO_new_accept("4444");
+
+/* First call to BIO_accept() sets up accept BIO */
+if (BIO_do_accept(abio) <= 0) {
+        fprintf(stderr, "Error setting up accept\en");
+        ERR_print_errors_fp(stderr);
+        exit(0);
+}
+
+/* Wait for incoming connection */
+if (BIO_do_accept(abio) <= 0) {
+        fprintf(stderr, "Error accepting connection\en");
+        ERR_print_errors_fp(stderr);
+        exit(0);
+}
+fprintf(stderr, "Connection 1 established\en");
+
+/* Retrieve BIO for connection */
+cbio = BIO_pop(abio);
+
+BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\en");
+fprintf(stderr, "Sent out data on connection 1\en");
+
+/* Wait for another connection */
+if (BIO_do_accept(abio) <= 0) {
+        fprintf(stderr, "Error accepting connection\en");
+        ERR_print_errors_fp(stderr);
+        exit(0);
+}
+fprintf(stderr, "Connection 2 established\en");
+
+/* Close accept BIO to refuse further connections */
+cbio2 = BIO_pop(abio);
+BIO_free(abio);
+
+BIO_puts(cbio2, "Connection 2: Sending out Data on second\en");
+fprintf(stderr, "Sent out data on connection 2\en");
+BIO_puts(cbio, "Connection 1: Second connection established\en");
+
+/* Close the two established connections */
+BIO_free(cbio);
+BIO_free(cbio2);
+.Ed