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

1 files changed, 332 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/BIO_s_connect.3 b/src/lib/libcrypto/man/BIO_s_connect.3
new file mode 100644
index 0000000000..960400e853
--- /dev/null
+++ b/src/lib/libcrypto/man/BIO_s_connect.3
@@ -0,0 +1,332 @@
+.Dd $Mdocdate: February 16 2015 $
+.Dt BIO_S_CONNECT 3
+.Os
+.Sh NAME
+.Nm BIO_s_connect ,
+.Nm BIO_new_connect ,
+.Nm BIO_set_conn_hostname ,
+.Nm BIO_set_conn_port ,
+.Nm BIO_set_conn_ip ,
+.Nm BIO_set_conn_int_port ,
+.Nm BIO_get_conn_hostname ,
+.Nm BIO_get_conn_port ,
+.Nm BIO_get_conn_ip ,
+.Nm BIO_get_conn_int_port ,
+.Nm BIO_set_nbio ,
+.Nm BIO_do_connect
+.Nd connect BIO
+.Sh SYNOPSIS
+.In openssl/bio.h
+.Ft BIO_METHOD *
+.Fo BIO_s_connect
+.Fa void
+.Fc
+.Ft BIO *
+.Fo BIO_new_connect
+.Fa "char *name"
+.Fc
+.Ft long
+.Fo BIO_set_conn_hostname
+.Fa "BIO *b"
+.Fa "char *name"
+.Fc
+.Ft long
+.Fo BIO_set_conn_port
+.Fa "BIO *b"
+.Fa "char *port"
+.Fc
+.Ft long
+.Fo BIO_set_conn_ip
+.Fa "BIO *b"
+.Fa "char *ip"
+.Fc
+.Ft long
+.Fo BIO_set_conn_int_port
+.Fa "BIO *b"
+.Fa "char *port"
+.Fc
+.Ft char *
+.Fo BIO_get_conn_hostname
+.Fa "BIO *b"
+.Fc
+.Ft char *
+.Fo BIO_get_conn_port
+.Fa "BIO *b"
+.Fc
+.Ft char *
+.Fo BIO_get_conn_ip
+.Fa "BIO *b"
+.Fa "dummy"
+.Fc
+.Ft long
+.Fo BIO_get_conn_int_port
+.Fa "BIO *b"
+.Fa "int port"
+.Fc
+.Ft long
+.Fo BIO_set_nbio
+.Fa "BIO *b"
+.Fa "long n"
+.Fc
+.Ft int
+.Fo BIO_do_connect
+.Fa "BIO *b"
+.Fc
+.Sh DESCRIPTION
+.Fn BIO_s_connect
+returns the connect BIO method.
+This is a wrapper around the platform's TCP/IP socket connection routines.
+.Pp
+Using connect BIOs, TCP/IP connections can be made 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 a connect BIO will perform I/O
+on the underlying connection.
+If no connection is established and the port and hostname (see below)
+is set up properly, then a connection is established first.
+.Pp
+Connect BIOs support
+.Xr BIO_puts 3
+but not
+.Xr BIO_gets 3 .
+.Pp
+If the close flag is set on a connect BIO, then any active connection
+is shutdown and the socket closed when the BIO is freed.
+.Pp
+Calling
+.Xr BIO_reset 3
+on a connect BIO will close any active connection and reset the BIO
+into a state where it can connect to the same host again.
+.Pp
+.Xr BIO_get_fd 3
+places the underlying socket in
+.Fa c
+if it is not
+.Dv NULL ,
+it also returns the socket.
+If
+.Fa c
+is not
+.Dv NULL
+it should be of type
+.Vt "int *" .
+.Pp
+.Fn BIO_set_conn_hostname
+uses the string
+.Fa name
+to set the hostname.
+The hostname can be an IP address.
+The hostname can also include the port in the form
+.Ar hostname : Ns Ar port .
+It is also acceptable to use the forms
+.Ar hostname Ns / Ns Pa any/other/path
+or
+.Ar hostname : Ns Ar port Ns / Ns Pa any/other/path .
+.Pp
+.Fn BIO_set_conn_port
+sets the port to
+.Fa port .
+.Fa port
+can be the numerical form or a string such as
+.Cm http .
+A string will be looked up first using
+.Xr getservbyname 3
+on the host platform, but if that fails
+a built-in table of port names will be used.
+Currently the list is
+.Cm http ,
+.Cm telnet ,
+.Cm socks ,
+.Cm https ,
+.Cm ssl ,
+.Cm ftp ,
+.Cm gopher ,
+and
+.Cm wais .
+.Pp
+.Fn BIO_set_conn_ip
+sets the IP address to
+.Fa ip
+using binary form, that is four bytes specifying the IP address
+in big-endian form.
+.Pp
+.Fn BIO_set_conn_int_port
+sets the port using
+.Fa port .
+.Fa port
+should
+be of type
+.Vt "int *" .
+.Pp
+.Fn BIO_get_conn_hostname
+returns the hostname of the connect BIO or
+.Dv NULL
+if the BIO is initialized but no hostname is set.
+This return value is an internal pointer which should not be modified.
+.Pp
+.Fn BIO_get_conn_port
+returns the port as a string.
+.Pp
+.Fn BIO_get_conn_ip
+returns the IP address in binary form.
+.Pp
+.Fn BIO_get_conn_int_port
+returns the port as an
+.Vt int .
+.Pp
+.Fn BIO_set_nbio
+sets the non blocking I/O flag to
+.Fa n .
+If
+.Fa n
+is zero then blocking I/O is set.
+If
+.Fa n
+is 1 then non blocking I/O is set.
+Blocking I/O is the default.
+The call to
+.Fn BIO_set_nbio
+should be made before the connection is established
+because non blocking I/O is set during the connect process.
+.Pp
+.Fn BIO_new_connect
+combines
+.Xr BIO_new 3
+and
+.Fn BIO_set_conn_hostname
+into a single call.
+It creates a new connect BIO with
+.Fa name .
+.Pp
+.Fn BIO_do_connect
+attempts to connect the supplied BIO.
+It returns 1 if the connection was established successfully.
+A zero or negative value is returned if the connection
+could not be established.
+The call
+.Xr BIO_should_retry 3
+should be used for non blocking connect BIOs
+to determine if the call should be retried.
+.Sh NOTES
+If blocking I/O is set then a non positive return value from any
+I/O call is caused by an error condition, although a zero return
+will normally mean that the connection was closed.
+.Pp
+If the port name is supplied as part of the host name then this will
+override any value set with
+.Fn BIO_set_conn_port .
+This may be undesirable if the application does not wish to allow
+connection to arbitrary ports.
+This can be avoided by checking for the presence of the
+.Sq \&:
+character in the passed hostname and either indicating an error
+or truncating the string at that point.
+.Pp
+The values returned by
+.Fn BIO_get_conn_hostname ,
+.Fn BIO_get_conn_port ,
+.Fn BIO_get_conn_ip ,
+and
+.Fn BIO_get_conn_int_port
+are updated when a connection attempt is made.
+Before any connection attempt the values returned
+are those set by the application itself.
+.Pp
+Applications do not have to call
+.Fn BIO_do_connect
+but may wish to do so to separate the connection process
+from other I/O processing.
+.Pp
+If non-blocking I/O is set,
+then retries will be requested as appropriate.
+.Pp
+It addition to
+.Xr BIO_should_read 3
+and
+.Xr BIO_should_write 3
+it is also possible for
+.Xr BIO_should_io_special 3
+to be true during the initial connection process with the reason
+.Dv BIO_RR_CONNECT .
+If this is returned, it is an indication
+that a connection attempt would block.
+The application should then take appropriate action to wait
+until the underlying socket has connected and retry the call.
+.Pp
+.Fn BIO_set_conn_hostname ,
+.Fn BIO_set_conn_port ,
+.Fn BIO_set_conn_ip ,
+.Fn BIO_set_conn_int_port ,
+.Fn BIO_get_conn_hostname ,
+.Fn BIO_get_conn_port ,
+.Fn BIO_get_conn_ip ,
+.Fn BIO_get_conn_int_port ,
+.Fn BIO_set_nbio ,
+and
+.Fn BIO_do_connect
+are macros.
+.Sh RETURN VALUES
+.Fn BIO_s_connect
+returns the connect BIO method.
+.Pp
+.Xr BIO_get_fd 3
+returns the socket or -1 if the BIO has not been initialized.
+.Pp
+.Fn BIO_set_conn_hostname ,
+.Fn BIO_set_conn_port ,
+.Fn BIO_set_conn_ip ,
+and
+.Fn BIO_set_conn_int_port
+always return 1.
+.Pp
+.Fn BIO_get_conn_hostname
+returns the connected hostname or
+.Dv NULL
+if none is set.
+.Pp
+.Fn BIO_get_conn_port
+returns a string representing the connected port or
+.Dv NULL
+if not set.
+.Pp
+.Fn BIO_get_conn_ip
+returns a pointer to the connected IP address in binary form
+or all zeros if not set.
+.Pp
+.Fn BIO_get_conn_int_port
+returns the connected port or 0 if none was set.
+.Pp
+.Fn BIO_set_nbio
+always returns 1.
+.Pp
+.Fn BIO_do_connect
+returns 1 if the connection was successfully
+established and 0 or -1 if the connection failed.
+.Sh EXAMPLES
+This example connects to a webserver on the local host and attempts
+to retrieve a page and copy the result to standard output.
+.Bd -literal -offset 2n
+BIO *cbio, *out;
+int len;
+char tmpbuf[1024];
+
+ERR_load_crypto_strings();
+cbio = BIO_new_connect("localhost:http");
+out = BIO_new_fp(stdout, BIO_NOCLOSE);
+if (BIO_do_connect(cbio) <= 0) {
+        fprintf(stderr, "Error connecting to server\en");
+        ERR_print_errors_fp(stderr);
+        /* whatever ... */
+}
+BIO_puts(cbio, "GET / HTTP/1.0\en\en");
+for(;;) {
+        len = BIO_read(cbio, tmpbuf, 1024);
+        if (len <= 0)
+                break;
+        BIO_write(out, tmpbuf, len);
+}
+BIO_free(cbio);
+BIO_free(out);
+.Ed