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_accept.3 | 387 ------------------------------------- 1 file changed, 387 deletions(-) delete mode 100644 src/lib/libcrypto/man/BIO_accept.3 (limited to 'src/lib/libcrypto/man/BIO_accept.3') diff --git a/src/lib/libcrypto/man/BIO_accept.3 b/src/lib/libcrypto/man/BIO_accept.3 deleted file mode 100644 index e2547ac0dd..0000000000 --- a/src/lib/libcrypto/man/BIO_accept.3 +++ /dev/null @@ -1,387 +0,0 @@ -.\" $OpenBSD: BIO_accept.3,v 1.2 2023/04/30 13:38:48 schwarze Exp $ -.\" -.\" Copyright (c) 2022 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. -.\" -.Dd $Mdocdate: April 30 2023 $ -.Dt BIO_ACCEPT 3 -.Os -.Sh NAME -.\" mentioned in OpenSSL documentation and still used internally in LibreSSL -.Nm BIO_get_host_ip , -.Nm BIO_get_port , -.Nm BIO_get_accept_socket , -.Nm BIO_accept , -.Nm BIO_sock_error , -.Nm BIO_sock_non_fatal_error , -.Nm BIO_sock_should_retry , -.\" used internally in LibreSSL and OpenSSL and not deprecated in OpenSSL -.Nm BIO_socket_nbio , -.\" mentioned in OpenSSL documentation and not deprecated in OpenSSL -.Nm BIO_set_tcp_ndelay -.\" deprecated in OpenSSL and unused anywhere, hence intentionally undocumented -.\" .Nm BIO_gethostbyname -.\" .Nm BIO_GHBN_CTRL_CACHE_SIZE -.\" .Nm BIO_GHBN_CTRL_FLUSH -.\" .Nm BIO_GHBN_CTRL_GET_ENTRY -.\" .Nm BIO_GHBN_CTRL_HITS -.\" .Nm BIO_GHBN_CTRL_MISSES -.\" .Nm BIO_socket_ioctl -.\" does almost nothing and used very rarely, hence intentionally undocumented -.\" .Nm BIO_sock_init -.\" .Nm BIO_sock_cleanup -.Nd wrappers for socket operations -.Sh SYNOPSIS -.In openssl/bio.h -.Ft int -.Fo BIO_get_host_ip -.Fa "const char *hostname" -.Fa "unsigned char *in_addr_buffer" -.Fc -.Ft int -.Fo BIO_get_port -.Fa "const char *servname" -.Fa "unsigned short *port" -.Fc -.Ft int -.Fo BIO_get_accept_socket -.Fa "char *host_port" -.Fa "int bind_mode" -.Fc -.Ft int -.Fo BIO_accept -.Fa "int socket" -.Fa "char **addr" -.Fc -.Ft int -.Fn BIO_sock_error "int socket" -.Ft int -.Fn BIO_sock_non_fatal_error "int errnum" -.Ft int -.Fn BIO_sock_should_retry "int retval" -.Ft int -.Fn BIO_socket_nbio "int socket" "int mode" -.Ft int -.Fn BIO_set_tcp_ndelay "int socket" "int on" -.Sh DESCRIPTION -.Fn BIO_get_host_ip -looks up one IPv4 address for the given -.Fa hostname -using -.Xr getaddrinfo 3 -and writes the first returned IPv4 address into -.Pf * Fa in_addr_buffer . -The caller is responsible for providing a buffer that is at least -.Fn sizeof in_addr_t -bytes long. -After a successful call, the caller needs to cast -.Fa in_addr_buffer -to -.Pq Vt in_addr_t * . -.Pp -.Fn BIO_get_port -looks up -.Fa servname -in the -.Xr services 5 -database using -.Xr getaddrinfo 3 -and stores the associated port number at the location specified by the -.Fa port -argument. -.Pp -.Fn BIO_get_accept_socket -creates an IPv4 TCP socket and -.Xr listen 2 Ns s -for incoming connections. -The string -.Fa host_port -is parsed. -If it contains a colon, the substring before the colon is interpreted -as a local hostname of the interface to -.Xr bind 2 -to. -If the hostname is empty, consists of a single asterisk -.Pq Qq *:... , -or if there is no colon, -.Dv INADDR_ANY -is used instead of a local hostname. -The rest of the string -.Fa host_port , -or the whole string if it contains no colon, -is treated as a service name. -The hostname and the service name are converted to a local IP address -and port number using -.Xr getaddrinfo 3 . -If -.Fa bind_mode -is the constant -.Dv BIO_BIND_REUSEADDR , -allowing local address reuse is attempted using -.Xr setsockopt 2 -with an argument of -.Dv SO_REUSEADDR -before calling -.Xr bind 2 . -.Pp -.Fn BIO_accept -calls -.Xr accept 2 -to receive one connection on the -.Fa socket . -When it receives a connection, it -.Xr free 3 Ns s -.Pf * Fa addr , -and if it is an IPv4 connection, it allocates a new string, -writes the peer IP address in dotted decimal form, a colon, -and the decimal port number into the string, and stores a pointer -to the string in -.Pf * Fa addr . -For other address families or if -.Xr getnameinfo 3 -or memory allocation fails, -.Pf * Fa addr -is set to -.Dv NULL -but -.Fn BIO_accept -succeeds anyway. -.Pp -.Fn BIO_sock_error -retrieves, clears, and returns the error status code of the -.Fa socket -by calling -.Xr getsockopt 2 -with arguments -.Dv SOL_SOCKET -and -.Dv SO_ERROR . -.Pp -.Fn BIO_sock_non_fatal_error -determines whether the error status code -.Fa errnum -represents a recoverable error. -.Pp -.Fn BIO_sock_should_retry -determines whether a recoverable error occurred by inspecting both -.Xr errno 2 -and -.Fa retval , -which is supposed to usually be -the return value of a previously called function like -.Fn BIO_accept , -.Xr BIO_read 3 , -or -.Xr BIO_write 3 . -.Pp -If -.Fa mode -is non-zero, -.Fn BIO_socket_nbio -switches the -.Fa socket -to non-blocking mode using -.Xr fcntl 2 . -If -.Fa mode -is 0, it switches to blocking mode. -.Pp -.Fn BIO_set_tcp_ndelay -sets the -.Dv TCP_NODELAY -option on the -.Fa socket -if -.Fa on -is 1 or clears it if -.Fa on -is 0; see -.Xr tcp 4 -for details. -.Sh RETURN VALUES -.Fn BIO_get_host_ip , -.Fn BIO_get_port , -and -.Fn BIO_socket_nbio -return 1 on success or 0 on failure. -.Pp -.Fn BIO_get_accept_socket -returns the file descriptor of the newly created listening socket or \-1 if -.Fa host_port -is -.Dv NULL , -no service is specified, or -.Xr getaddrinfo 3 , -.Xr socket 2 , -.Xr bind 2 , -.Xr listen 2 , -or memory allocation fails. -.Pp -.Fn BIO_accept -returns the file descriptor of the received connection, -\-1 on fatal errors, that is, when -.Fa addr -is -.Dv NULL -or -.Xr accept 2 -fails fatally, or \-2 when -.Xr accept 2 -fails in a non-fatal way and might succeed when retried later. -.Pp -.Fn BIO_sock_error -returns an error status code like -.Dv EAGAIN , -.Dv ECONNABORTED , -.Dv ECONNREFUSED , -.Dv ECONNRESET , -.Dv ELOOP , -.Dv EMSGSIZE , -.Dv ENOBUFS , -.Dv ENOTCONN , -.Dv EPIPE , -.Dv ETIMEDOUT , -or others, 0 if the -.Fa socket -is not in an error state, or 1 if -.Xr getsockopt 2 -fails. -.Pp -.Fn BIO_sock_non_fatal_error -returns 1 if -.Fa errnum -is -.Dv EAGAIN , -.Dv EALREADY , -.Dv EINPROGRESS , -.Dv EINTR , -or -.Dv ENOTCONN -and 0 otherwise, even if -.Fa errnum -is 0. -.Pp -.Fn BIO_sock_should_retry -returns 1 if -.Fn BIO_sock_non_fatal_error errno -is 1 and -.Fa retval -is either 0 or \-1, or 0 otherwise. -.Pp -.Fn BIO_set_tcp_ndelay -returns 0 on success or \-1 on failure. -.Sh ERRORS -If -.Fn BIO_get_host_ip , -.Fn BIO_get_port , -or -.Fn BIO_get_accept_socket -fail or -.Fn BIO_accept -fails fatally, the following diagnostics can be retrieved with -.Xr ERR_get_error 3 , -.Xr ERR_GET_REASON 3 , -and -.Xr ERR_reason_error_string 3 : -.Bl -tag -width Ds -.It Dv BIO_R_ACCEPT_ERROR Qq "accept error" -.Xr accept 2 -failed fatally in -.Fn BIO_accept . -.It Dv BIO_R_BAD_HOSTNAME_LOOKUP Qq "bad hostname lookup" -.Xr getaddrinfo 3 -failed or -.Fa hostname -was -.Dv NULL -in -.Fn BIO_get_host_ip , -or -.Xr getaddrinfo 3 -failed in -.Fn BIO_get_accept_socket . -.It Dv BIO_R_INVALID_ARGUMENT Qq "invalid argument" -.Xr getaddrinfo 3 -failed in -.Fn BIO_get_port . -.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure" -Memory allocation failed in -.Fn BIO_get_accept_socket , -or -.Fn BIO_accept -.Em succeeded -but was unable to allocate memory for -.Pf * Fa addr . -For -.Fn BIO_accept , -the returned file descriptor is valid, -and communication with the peer can be attempted using it. -.It Dv BIO_R_NO_PORT_SPECIFIED Qq "no port specified" -The -.Fa servname -argument was -.Dv NULL -in -.Fn BIO_get_port , -or -.Fa host_port -was -.Dv NULL -or ended after the first colon in -.Fn BIO_get_accept_socket . -.It Dv BIO_R_NULL_PARAMETER Qq "null parameter" -The -.Fa addr -argument was -.Dv NULL -in -.Fn BIO_accept . -.It Dv BIO_R_UNABLE_TO_BIND_SOCKET Qq "unable to bind socket" -.Xr bind 2 -failed in -.Fn BIO_get_accept_socket . -.It Dv BIO_R_UNABLE_TO_CREATE_SOCKET Qq "unable to create socket" -.Xr socket 2 -failed in -.Fn BIO_get_accept_socket . -.It Dv BIO_R_UNABLE_TO_LISTEN_SOCKET Qq "unable to listen socket" -.Xr listen 2 -failed in -.Fn BIO_get_accept_socket . -.El -.Sh SEE ALSO -.Xr bind 2 , -.Xr connect 2 , -.Xr errno 2 , -.Xr fcntl 2 , -.Xr getsockopt 2 , -.Xr listen 2 , -.Xr sigaction 2 , -.Xr socket 2 , -.Xr BIO_new 3 , -.Xr BIO_read 3 , -.Xr getaddrinfo 3 , -.Xr ip 4 , -.Xr tcp 4 -.Sh HISTORY -.Fn BIO_sock_should_retry -first appeared in SSLeay 0.6.5 and the other functions except -.Fn BIO_socket_nbio -in SSLeay 0.8.0. -They have all been available since -.Ox 2.4 . -.Pp -.Fn BIO_socket_nbio -first appeared in SSLeay 0.9.1 and has been available since -.Ox 2.6 . -- cgit v1.2.3-55-g6feb