1.\" $OpenBSD: BIO_s_fd.3,v 1.13 2023/11/16 20:19:23 schwarze Exp $ 2.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org> 8.\" 9.\" Permission to use, copy, modify, and distribute this software for any 10.\" purpose with or without fee is hereby granted, provided that the above 11.\" copyright notice and this permission notice appear in all copies. 12.\" 13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 20.\" 21.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 22.\" Copyright (c) 2000 The OpenSSL Project. All rights reserved. 23.\" 24.\" Redistribution and use in source and binary forms, with or without 25.\" modification, are permitted provided that the following conditions 26.\" are met: 27.\" 28.\" 1. Redistributions of source code must retain the above copyright 29.\" notice, this list of conditions and the following disclaimer. 30.\" 31.\" 2. Redistributions in binary form must reproduce the above copyright 32.\" notice, this list of conditions and the following disclaimer in 33.\" the documentation and/or other materials provided with the 34.\" distribution. 35.\" 36.\" 3. All advertising materials mentioning features or use of this 37.\" software must display the following acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 40.\" 41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 42.\" endorse or promote products derived from this software without 43.\" prior written permission. For written permission, please contact 44.\" openssl-core@openssl.org. 45.\" 46.\" 5. Products derived from this software may not be called "OpenSSL" 47.\" nor may "OpenSSL" appear in their names without prior written 48.\" permission of the OpenSSL Project. 49.\" 50.\" 6. Redistributions of any form whatsoever must retain the following 51.\" acknowledgment: 52.\" "This product includes software developed by the OpenSSL Project 53.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 54.\" 55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 58.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 66.\" OF THE POSSIBILITY OF SUCH DAMAGE. 67.\" 68.Dd $Mdocdate: November 16 2023 $ 69.Dt BIO_S_FD 3 70.Os 71.Sh NAME 72.Nm BIO_s_fd , 73.Nm BIO_set_fd , 74.Nm BIO_get_fd , 75.Nm BIO_new_fd , 76.Nm BIO_fd_non_fatal_error , 77.Nm BIO_fd_should_retry 78.Nd file descriptor BIO 79.Sh SYNOPSIS 80.In openssl/bio.h 81.Ft const BIO_METHOD * 82.Fo BIO_s_fd 83.Fa "void" 84.Fc 85.Ft long 86.Fo BIO_set_fd 87.Fa "BIO *b" 88.Fa "int fd" 89.Fa "long close_flag" 90.Fc 91.Ft long 92.Fo BIO_get_fd 93.Fa "BIO *b" 94.Fa "int *c" 95.Fc 96.Ft BIO * 97.Fo BIO_new_fd 98.Fa "int fd" 99.Fa "int close_flag" 100.Fc 101.Ft int 102.Fn BIO_fd_non_fatal_error "int errnum" 103.Ft int 104.Fn BIO_fd_should_retry "int retval" 105.Sh DESCRIPTION 106.Fn BIO_s_fd 107returns the file descriptor BIO method. 108This is a wrapper around the platform's file descriptor routines such as 109.Xr read 2 110and 111.Xr write 2 . 112.Pp 113.Xr BIO_read 3 114and 115.Xr BIO_write 3 116read or write the underlying descriptor. 117.Xr BIO_puts 3 118is supported but 119.Xr BIO_gets 3 120is not. 121.Pp 122If the close flag is set, 123.Xr close 2 124is called on the underlying file descriptor when the 125.Vt BIO 126is freed. 127.Pp 128.Xr BIO_reset 3 129attempts to set the file pointer to the start of the file using 130.Fn lseek fd 0 0 . 131.Pp 132.Xr BIO_seek 3 133sets the file pointer to position 134.Fa ofs 135from start of file using 136.Fn lseek fd ofs 0 . 137.Pp 138.Xr BIO_tell 3 139returns the current file position by calling 140.Fn lseek fd 0 1 . 141.Pp 142.Fn BIO_set_fd 143sets the file descriptor of 144.Vt BIO 145.Fa b 146to 147.Fa fd 148and the close flag to 149.Fa close_flag . 150.Pp 151.Fn BIO_get_fd 152places the file descriptor in 153.Fa c 154if it is not 155.Dv NULL 156and also returns the file descriptor. 157.Pp 158.Fn BIO_new_fd 159returns a file descriptor BIO using 160.Fa fd 161and 162.Fa close_flag . 163.Pp 164.Fn BIO_fd_non_fatal_error 165determines whether the error status code 166.Fa errnum 167represents a recoverable error. 168.Fn BIO_fd_should_retry 169determines whether a recoverable error occurred by inspecting both 170.Xr errno 2 171and 172.Fa retval , 173which is supposed to usually be 174the return value of a previously called function like 175.Xr BIO_read 3 176or 177.Xr BIO_write 3 . 178These two functions are mostly used internally; in application code, 179it is usually easier and more robust to use 180.Xr BIO_should_retry 3 , 181which works for any BIO type. 182.Pp 183The behaviour of 184.Xr BIO_read 3 185and 186.Xr BIO_write 3 187depends on the behavior of the platform's 188.Xr read 2 189and 190.Xr write 2 191calls on the descriptor. 192If the underlying file descriptor is in a non-blocking mode, 193then the BIO will behave in the manner described in the 194.Xr BIO_read 3 195and 196.Xr BIO_should_retry 3 197manual pages. 198.Pp 199File descriptor BIOs should not be used for socket I/O. 200Use socket BIOs instead. 201.Pp 202.Xr BIO_ctrl 3 203.Fa cmd 204arguments correspond to macros as follows: 205.Bl -column BIO_CTRL_GET_CLOSE BIO_get_close(3) -offset 3n 206.It Fa cmd No constant Ta corresponding macro 207.It Dv BIO_C_FILE_SEEK Ta Xr BIO_seek 3 208.It Dv BIO_C_FILE_TELL Ta Xr BIO_tell 3 209.It Dv BIO_C_GET_FD Ta Fn BIO_get_fd 210.It Dv BIO_C_SET_FD Ta Fn BIO_set_fd 211.It Dv BIO_CTRL_GET_CLOSE Ta Xr BIO_get_close 3 212.It Dv BIO_CTRL_RESET Ta Xr BIO_reset 3 213.It Dv BIO_CTRL_SET_CLOSE Ta Xr BIO_set_close 3 214.El 215.Sh RETURN VALUES 216.Fn BIO_s_fd 217returns the file descriptor BIO method. 218.Pp 219When called on a file descriptor BIO object, 220.Xr BIO_method_type 3 221returns the constant 222.Dv BIO_TYPE_FD 223and 224.Xr BIO_method_name 3 225returns a pointer to the static string 226.Qq file descriptor . 227.Pp 228.Fn BIO_set_fd 229always returns 1. 230.Pp 231.Fn BIO_get_fd 232returns the file descriptor or -1 if the 233.Vt BIO 234has not been initialized. 235.Pp 236.Fn BIO_new_fd 237returns the newly allocated 238.Vt BIO 239or 240.Dv NULL 241if an error occurred. 242.Pp 243.Fn BIO_fd_non_fatal_error 244returns 1 if 245.Fa errnum 246is 247.Dv EAGAIN , 248.Dv EALREADY , 249.Dv EINPROGRESS , 250.Dv EINTR , 251or 252.Dv ENOTCONN 253and 0 otherwise, even if 254.Fa errnum 255is 0. 256.Pp 257.Fn BIO_fd_should_retry 258returns 1 if 259.Fn BIO_fd_non_fatal_error errno 260is 1 and 261.Fa retval 262is either 0 or \-1, or 0 otherwise. 263.Sh EXAMPLES 264This is a file descriptor BIO version of "Hello World": 265.Bd -literal -offset indent 266BIO *out; 267out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE); 268BIO_printf(out, "Hello World\en"); 269BIO_free(out); 270.Ed 271.Sh SEE ALSO 272.Xr BIO_new 3 , 273.Xr BIO_read 3 , 274.Xr BIO_s_socket 3 , 275.Xr BIO_seek 3 , 276.Xr BIO_should_retry 3 277.Sh HISTORY 278.Fn BIO_s_fd , 279.Fn BIO_set_fd , 280and 281.Fn BIO_get_fd 282first appeared in SSLeay 0.6.0, 283.Fn BIO_fd_should_retry 284in SSLeay 0.6.5, and 285.Fn BIO_new_fd 286and 287.Fn BIO_fd_non_fatal_error 288in SSLeay 0.8.0. 289All these functions have been available since 290.Ox 2.4 . 291