From eb8dd9dca1228af0cd132f515509051ecfabf6f6 Mon Sep 17 00:00:00 2001 From: cvs2svn Date: Mon, 14 Apr 2025 17:32:06 +0000 Subject: This commit was manufactured by cvs2git to create tag 'tb_20250414'. --- src/lib/libcrypto/man/BIO_s_connect.3 | 503 ---------------------------------- 1 file changed, 503 deletions(-) delete mode 100644 src/lib/libcrypto/man/BIO_s_connect.3 (limited to 'src/lib/libcrypto/man/BIO_s_connect.3') diff --git a/src/lib/libcrypto/man/BIO_s_connect.3 b/src/lib/libcrypto/man/BIO_s_connect.3 deleted file mode 100644 index bce68a26b9..0000000000 --- a/src/lib/libcrypto/man/BIO_s_connect.3 +++ /dev/null @@ -1,503 +0,0 @@ -.\" $OpenBSD: BIO_s_connect.3,v 1.19 2023/04/30 13:53:54 schwarze Exp $ -.\" full merge up to: OpenSSL 0e474b8b Nov 1 15:45:49 2015 +0100 -.\" -.\" This file is a derived work. -.\" The changes are covered by the following Copyright and license: -.\" -.\" Copyright (c) 2023 Ingo Schwarze -.\" -.\" Permission to use, copy, modify, and distribute this software for any -.\" purpose with or without fee is hereby granted, provided that the above -.\" copyright notice and this permission notice appear in all copies. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF -.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -.\" -.\" The original file was written by Dr. Stephen Henson . -.\" Copyright (c) 2000, 2015 The OpenSSL Project. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in -.\" the documentation and/or other materials provided with the -.\" distribution. -.\" -.\" 3. All advertising materials mentioning features or use of this -.\" software must display the following acknowledgment: -.\" "This product includes software developed by the OpenSSL Project -.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" -.\" -.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to -.\" endorse or promote products derived from this software without -.\" prior written permission. For written permission, please contact -.\" openssl-core@openssl.org. -.\" -.\" 5. Products derived from this software may not be called "OpenSSL" -.\" nor may "OpenSSL" appear in their names without prior written -.\" permission of the OpenSSL Project. -.\" -.\" 6. Redistributions of any form whatsoever must retain the following -.\" acknowledgment: -.\" "This product includes software developed by the OpenSSL Project -.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY -.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR -.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT -.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, -.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED -.\" OF THE POSSIBILITY OF SUCH DAMAGE. -.\" -.Dd $Mdocdate: April 30 2023 $ -.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 const BIO_METHOD * -.Fo BIO_s_connect -.Fa void -.Fc -.Ft BIO * -.Fo BIO_new_connect -.Fa "const 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" -.Fc -.Ft long -.Fo BIO_get_conn_int_port -.Fa "BIO *b" -.Fc -.Ft long -.Fo BIO_set_nbio -.Fa "BIO *b" -.Fa "long n" -.Fc -.Ft long -.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 -and also returns the socket. -If -.Fa c -is not -.Dv NULL , -it should be of type -.Vt "int *" . -.Pp -.Xr BIO_set_info_callback 3 -and -.Xr BIO_callback_ctrl 3 -with a -.Fa cmd -of -.Dv BIO_CTRL_SET_CALLBACK -save the pointer to the -.Fa cb -function internally in -.Fa b -and -.Xr BIO_get_info_callback 3 -retrieves this function pointer. -If such an info callback is installed, it is invoked whenever -a state change or error occurs in the connect BIO state machine. -The arguments of the callback include the new -.Fa state -in case of a state change or the old -.Fa state -in case of an error and the value -.Fa res -that the state machine would return to whatever operation invoked it -if no info callback had been installed. -If an info callback is installed, the state machine -returns the return value of the info callback instead. -Consequently, the info callback is supposed to usually return -.Fa res . -The precise effect of the return value depends on which operation -the state machine was invoked from. -Usually, \-1 is used to indicate failure and return values less than -or equal to zero abort the operation in question, whereas positive -values indicate success and allow the operation to proceed. -.Pp -The -.Fa state -constants passed to the callback are named according to -which operation needs to be performed next. -They are listed here in the order the states are passed through: -.Pp -.Bl -tag -width BIO_CONN_S_BLOCKED_CONNECT -offset 3n -compact -.It Dv BIO_CONN_S_BEFORE -The BIO is idle and no connection has been initiated yet. -.It Dv BIO_CONN_S_GET_IP -The hostname to connect to needs to be converted to an IP address. -.It Dv BIO_CONN_S_GET_PORT -The service name to connect to needs to be converted to a TCP port number. -.It Dv BIO_CONN_S_CREATE_SOCKET -The TCP socket needs to be created with the -.Xr socket 2 -system call. -.It Dv BIO_CONN_S_NBIO -Socket options may need to be set using -.Xr fcntl 2 -and -.Xr setsockopt 2 . -.It Dv BIO_CONN_S_CONNECT -The connection needs to be initiated with the -.Xr connect 2 -system call. -.It Dv BIO_CONN_S_BLOCKED_CONNECT -The -.Xr connect 2 -system call would have blocked and needs to be tried again. -.It Dv BIO_CONN_S_OK -The connection has been established and can now be used to transfer data. -.El -.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 -is looked up as a service using -.Xr getaddrinfo 3 . -.Pp -.Fn BIO_set_conn_ip -sets the IP address to -.Fa ip -using binary form i.e. 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. -This return value is an internal pointer which should not be modified. -.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. -.Pp -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 -In 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 -When a chain containing a connect BIO is copied with -.Xr BIO_dup_chain 3 , -.Fn BIO_set_conn_hostname , -.Fn BIO_set_conn_port , -.Fn BIO_set_nbio , -and -.Xr BIO_set_info_callback 3 -are called internally to automatically copy the hostname, port, -non-blocking I/O flag, and info callback from the original BIO object -to the new one. -.Pp -.Xr BIO_ctrl 3 -.Fa cmd -and -.Fa larg -arguments correspond to macros as follows: -.Bl -column BIO_C_DO_STATE_MACHINE larg BIO_get_conn_hostname(3) -offset 3n -.It Fa cmd No constant Ta Fa larg Ta corresponding macro -.It Dv BIO_C_DO_STATE_MACHINE Ta 0 Ta Fn BIO_do_connect -.It Dv BIO_C_GET_CONNECT Ta 0 Ta Fn BIO_get_conn_hostname -.It Ta 1 Ta Fn BIO_get_conn_port -.It Ta 2 Ta Fn BIO_get_conn_ip -.It Ta 3 Ta Fn BIO_get_conn_int_port -.It Dv BIO_C_GET_FD Ta 0 Ta Xr BIO_get_fd 3 -.It Dv BIO_C_SET_CONNECT Ta 0 Ta Fn BIO_set_conn_hostname -.It Ta 1 Ta Fn BIO_set_conn_port -.It Ta 2 Ta Fn BIO_set_conn_ip -.It Ta 3 Ta Fn BIO_set_conn_int_port -.It Dv BIO_C_SET_NBIO Ta Fa n Ta Fn BIO_set_nbio -.It Dv BIO_CTRL_GET_CLOSE Ta 0 Ta Xr BIO_get_close 3 -.It Dv BIO_CTRL_RESET Ta 0 Ta Xr BIO_reset 3 -.It Dv BIO_CTRL_SET_CLOSE Ta Fa flag Ta Xr BIO_set_close 3 -.El -.Sh RETURN VALUES -.Fn BIO_s_connect -returns the connect BIO method. -.Pp -When called on a connect BIO object, -.Xr BIO_method_type 3 -returns the constant -.Dv BIO_TYPE_CONNECT -and -.Xr BIO_method_name 3 -returns a pointer to the static string -.Qq socket connect . -.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 -.Sh SEE ALSO -.Xr BIO_new 3 -.Sh HISTORY -.Fn BIO_s_connect , -.Fn BIO_new_connect , -.Fn BIO_set_nbio , -and -.Fn BIO_do_connect -first appeared in SSLeay 0.8.0. -.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 , -and -.Fn BIO_get_conn_int_port -first appeared in SSLeay 0.9.0. -All these functions have been available since -.Ox 2.4 . -- cgit v1.2.3-55-g6feb