third batch of perlpod(1) to mdoc(7) conversion

1 files changed, 115 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/BIO_read.3 b/src/lib/libcrypto/man/BIO_read.3
new file mode 100644
index 0000000000..3114ab3da4
--- /dev/null
+++ b/src/lib/libcrypto/man/BIO_read.3
@@ -0,0 +1,115 @@
+.Dd $Mdocdate: February 16 2015 $
+.Dt BIO_READ 3
+.Os
+.Sh NAME
+.Nm BIO_read ,
+.Nm BIO_write ,
+.Nm BIO_gets ,
+.Nm BIO_puts
+.Nd BIO I/O functions
+.Sh SYNOPSIS
+.In openssl/bio.h
+.Ft int
+.Fo BIO_read
+.Fa "BIO *b"
+.Fa "void *buf"
+.Fa "int len"
+.Fc
+.Ft int
+.Fo BIO_gets
+.Fa "BIO *b"
+.Fa "char *buf"
+.Fa "int size"
+.Fc
+.Ft int
+.Fo BIO_write
+.Fa "BIO *b"
+.Fa "const void *buf"
+.Fa "int len"
+.Fc
+.Ft int
+.Fo BIO_puts
+.Fa "BIO *b"
+.Fa "const char *buf"
+.Fc
+.Sh DESCRIPTION
+.Fn BIO_read
+attempts to read
+.Fa len
+bytes from BIO
+.Fa b
+and places the data in
+.Fa buf .
+.Pp
+.Fn BIO_gets
+performs the BIOs "gets" operation and places the data in
+.Fa buf .
+Usually this operation will attempt to read a line of data
+from the BIO of maximum length
+.Fa len .
+There are exceptions to this however, for example
+.Fn BIO_gets
+on a digest BIO will calculate and return the digest
+and other BIOs may not support
+.Fn BIO_gets
+at all.
+.Pp
+.Fn BIO_write
+attempts to write
+.Fa len
+bytes from
+.Fa buf
+to BIO
+.Fa b .
+.Pp
+.Fn BIO_puts
+attempts to write a null terminated string
+.Fa buf
+to BIO
+.Fa b .
+.Sh RETURN VALUES
+All these functions return either the amount of data successfully
+read or written (if the return value is positive) or that no data
+was successfully read or written if the result is 0 or -1.
+If the return value is -2, then the operation is not implemented
+in the specific BIO type.
+.Sh NOTES
+A 0 or -1 return is not necessarily an indication of an error.
+In particular when the source/sink is non-blocking or of a certain type
+it may merely be an indication that no data is currently available and that
+the application should retry the operation later.
+.Pp
+One technique sometimes used with blocking sockets
+is to use a system call (such as
+.Xr select 2 ,
+.Xr poll 2
+or equivalent) to determine when data is available and then call
+.Xr read 3
+to read the data.
+The equivalent with BIOs (that is call
+.Xr select 2
+on the underlying I/O structure and then call
+.Fn BIO_read
+to read the data) should
+.Em not
+be used because a single call to
+.Fn BIO_read
+can cause several reads (and writes in the case of SSL BIOs)
+on the underlying I/O structure and may block as a result.
+Instead
+.Xr select 2
+(or equivalent) should be combined with non blocking I/O
+so successive reads will request a retry instead of blocking.
+.Pp
+See
+.Xr BIO_should_retry 3
+for details of how to determine the cause of a retry and other I/O issues.
+.Pp
+If the
+.Fn BIO_gets
+function is not supported by a BIO then it is possible to
+work around this by adding a buffering BIO
+.Xr BIO_f_buffer 3
+to the chain.
+.Sh SEE ALSO
+.Xr BIO_should_retry 3