.\"	$OpenBSD: BIO_s_fd.3,v 1.4 2016/11/07 15:52:47 jmc Exp $
.\"
.Dd $Mdocdate: November 7 2016 $
.Dt BIO_S_FD 3
.Os
.Sh NAME
.Nm BIO_s_fd ,
.Nm BIO_set_fd ,
.Nm BIO_get_fd ,
.Nm BIO_new_fd
.Nd file descriptor BIO
.Sh SYNOPSIS
.In openssl/bio.h
.Ft 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
.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 .
It is currently implemented as a macro.
.Pp
.Fn BIO_get_fd
places the file descriptor in
.Fa c
if it is not
.Dv NULL
and also returns the file descriptor.
It is currently implemented as a macro.
.Pp
.Fn BIO_new_fd
returns a file descriptor BIO using
.Fa fd
and
.Fa close_flag .
.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.
.Sh RETURN VALUES
.Fn BIO_s_fd
returns the file descriptor BIO method.
.Pp
.Xr BIO_reset 3
returns zero for success and -1 if an error occurred.
.Xr BIO_seek 3
and
.Xr BIO_tell 3
return the current file position or -1 if an error occurred.
These values reflect the underlying
.Xr lseek 2
behaviour.
.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.
.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_read 3 ,
.Xr BIO_s_socket 3 ,
.Xr BIO_seek 3