291 lines
7.7 KiB
Groff
291 lines
7.7 KiB
Groff
.\" $OpenBSD: BIO_s_fd.3,v 1.13 2023/11/16 20:19:23 schwarze Exp $
|
|
.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
|
|
.\"
|
|
.\" This file is a derived work.
|
|
.\" The changes are covered by the following Copyright and license:
|
|
.\"
|
|
.\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org>
|
|
.\"
|
|
.\" 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 <steve@openssl.org>.
|
|
.\" Copyright (c) 2000 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: November 16 2023 $
|
|
.Dt BIO_S_FD 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm BIO_s_fd ,
|
|
.Nm BIO_set_fd ,
|
|
.Nm BIO_get_fd ,
|
|
.Nm BIO_new_fd ,
|
|
.Nm BIO_fd_non_fatal_error ,
|
|
.Nm BIO_fd_should_retry
|
|
.Nd file descriptor BIO
|
|
.Sh SYNOPSIS
|
|
.In openssl/bio.h
|
|
.Ft const BIO_METHOD *
|
|
.Fo BIO_s_fd
|
|
.Fa "void"
|
|
.Fc
|
|
.Ft long
|
|
.Fo BIO_set_fd
|
|
.Fa "BIO *b"
|
|
.Fa "int fd"
|
|
.Fa "long close_flag"
|
|
.Fc
|
|
.Ft long
|
|
.Fo BIO_get_fd
|
|
.Fa "BIO *b"
|
|
.Fa "int *c"
|
|
.Fc
|
|
.Ft BIO *
|
|
.Fo BIO_new_fd
|
|
.Fa "int fd"
|
|
.Fa "int close_flag"
|
|
.Fc
|
|
.Ft int
|
|
.Fn BIO_fd_non_fatal_error "int errnum"
|
|
.Ft int
|
|
.Fn BIO_fd_should_retry "int retval"
|
|
.Sh DESCRIPTION
|
|
.Fn BIO_s_fd
|
|
returns the file descriptor BIO method.
|
|
This is a wrapper around the platform's file descriptor routines such as
|
|
.Xr read 2
|
|
and
|
|
.Xr write 2 .
|
|
.Pp
|
|
.Xr BIO_read 3
|
|
and
|
|
.Xr BIO_write 3
|
|
read or write the underlying descriptor.
|
|
.Xr BIO_puts 3
|
|
is supported but
|
|
.Xr BIO_gets 3
|
|
is not.
|
|
.Pp
|
|
If the close flag is set,
|
|
.Xr close 2
|
|
is called on the underlying file descriptor when the
|
|
.Vt BIO
|
|
is freed.
|
|
.Pp
|
|
.Xr BIO_reset 3
|
|
attempts to set the file pointer to the start of the file using
|
|
.Fn lseek fd 0 0 .
|
|
.Pp
|
|
.Xr BIO_seek 3
|
|
sets the file pointer to position
|
|
.Fa ofs
|
|
from start of file using
|
|
.Fn lseek fd ofs 0 .
|
|
.Pp
|
|
.Xr BIO_tell 3
|
|
returns the current file position by calling
|
|
.Fn lseek fd 0 1 .
|
|
.Pp
|
|
.Fn BIO_set_fd
|
|
sets the file descriptor of
|
|
.Vt BIO
|
|
.Fa b
|
|
to
|
|
.Fa fd
|
|
and the close flag to
|
|
.Fa close_flag .
|
|
.Pp
|
|
.Fn BIO_get_fd
|
|
places the file descriptor in
|
|
.Fa c
|
|
if it is not
|
|
.Dv NULL
|
|
and also returns the file descriptor.
|
|
.Pp
|
|
.Fn BIO_new_fd
|
|
returns a file descriptor BIO using
|
|
.Fa fd
|
|
and
|
|
.Fa close_flag .
|
|
.Pp
|
|
.Fn BIO_fd_non_fatal_error
|
|
determines whether the error status code
|
|
.Fa errnum
|
|
represents a recoverable error.
|
|
.Fn BIO_fd_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
|
|
.Xr BIO_read 3
|
|
or
|
|
.Xr BIO_write 3 .
|
|
These two functions are mostly used internally; in application code,
|
|
it is usually easier and more robust to use
|
|
.Xr BIO_should_retry 3 ,
|
|
which works for any BIO type.
|
|
.Pp
|
|
The behaviour of
|
|
.Xr BIO_read 3
|
|
and
|
|
.Xr BIO_write 3
|
|
depends on the behavior of the platform's
|
|
.Xr read 2
|
|
and
|
|
.Xr write 2
|
|
calls on the descriptor.
|
|
If the underlying file descriptor is in a non-blocking mode,
|
|
then the BIO will behave in the manner described in the
|
|
.Xr BIO_read 3
|
|
and
|
|
.Xr BIO_should_retry 3
|
|
manual pages.
|
|
.Pp
|
|
File descriptor BIOs should not be used for socket I/O.
|
|
Use socket BIOs instead.
|
|
.Pp
|
|
.Xr BIO_ctrl 3
|
|
.Fa cmd
|
|
arguments correspond to macros as follows:
|
|
.Bl -column BIO_CTRL_GET_CLOSE BIO_get_close(3) -offset 3n
|
|
.It Fa cmd No constant Ta corresponding macro
|
|
.It Dv BIO_C_FILE_SEEK Ta Xr BIO_seek 3
|
|
.It Dv BIO_C_FILE_TELL Ta Xr BIO_tell 3
|
|
.It Dv BIO_C_GET_FD Ta Fn BIO_get_fd
|
|
.It Dv BIO_C_SET_FD Ta Fn BIO_set_fd
|
|
.It Dv BIO_CTRL_GET_CLOSE Ta Xr BIO_get_close 3
|
|
.It Dv BIO_CTRL_RESET Ta Xr BIO_reset 3
|
|
.It Dv BIO_CTRL_SET_CLOSE Ta Xr BIO_set_close 3
|
|
.El
|
|
.Sh RETURN VALUES
|
|
.Fn BIO_s_fd
|
|
returns the file descriptor BIO method.
|
|
.Pp
|
|
When called on a file descriptor BIO object,
|
|
.Xr BIO_method_type 3
|
|
returns the constant
|
|
.Dv BIO_TYPE_FD
|
|
and
|
|
.Xr BIO_method_name 3
|
|
returns a pointer to the static string
|
|
.Qq file descriptor .
|
|
.Pp
|
|
.Fn BIO_set_fd
|
|
always returns 1.
|
|
.Pp
|
|
.Fn BIO_get_fd
|
|
returns the file descriptor or -1 if the
|
|
.Vt BIO
|
|
has not been initialized.
|
|
.Pp
|
|
.Fn BIO_new_fd
|
|
returns the newly allocated
|
|
.Vt BIO
|
|
or
|
|
.Dv NULL
|
|
if an error occurred.
|
|
.Pp
|
|
.Fn BIO_fd_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_fd_should_retry
|
|
returns 1 if
|
|
.Fn BIO_fd_non_fatal_error errno
|
|
is 1 and
|
|
.Fa retval
|
|
is either 0 or \-1, or 0 otherwise.
|
|
.Sh EXAMPLES
|
|
This is a file descriptor BIO version of "Hello World":
|
|
.Bd -literal -offset indent
|
|
BIO *out;
|
|
out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);
|
|
BIO_printf(out, "Hello World\en");
|
|
BIO_free(out);
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr BIO_new 3 ,
|
|
.Xr BIO_read 3 ,
|
|
.Xr BIO_s_socket 3 ,
|
|
.Xr BIO_seek 3 ,
|
|
.Xr BIO_should_retry 3
|
|
.Sh HISTORY
|
|
.Fn BIO_s_fd ,
|
|
.Fn BIO_set_fd ,
|
|
and
|
|
.Fn BIO_get_fd
|
|
first appeared in SSLeay 0.6.0,
|
|
.Fn BIO_fd_should_retry
|
|
in SSLeay 0.6.5, and
|
|
.Fn BIO_new_fd
|
|
and
|
|
.Fn BIO_fd_non_fatal_error
|
|
in SSLeay 0.8.0.
|
|
All these functions have been available since
|
|
.Ox 2.4 .
|