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

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 @@
	1	.Dd $Mdocdate: February 16 2015 $
	2	.Dt BIO_READ 3
	3	.Os
	4	.Sh NAME
	5	.Nm BIO_read ,
	6	.Nm BIO_write ,
	7	.Nm BIO_gets ,
	8	.Nm BIO_puts
	9	.Nd BIO I/O functions
	10	.Sh SYNOPSIS
	11	.In openssl/bio.h
	12	.Ft int
	13	.Fo BIO_read
	14	.Fa "BIO *b"
	15	.Fa "void *buf"
	16	.Fa "int len"
	17	.Fc
	18	.Ft int
	19	.Fo BIO_gets
	20	.Fa "BIO *b"
	21	.Fa "char *buf"
	22	.Fa "int size"
	23	.Fc
	24	.Ft int
	25	.Fo BIO_write
	26	.Fa "BIO *b"
	27	.Fa "const void *buf"
	28	.Fa "int len"
	29	.Fc
	30	.Ft int
	31	.Fo BIO_puts
	32	.Fa "BIO *b"
	33	.Fa "const char *buf"
	34	.Fc
	35	.Sh DESCRIPTION
	36	.Fn BIO_read
	37	attempts to read
	38	.Fa len
	39	bytes from BIO
	40	.Fa b
	41	and places the data in
	42	.Fa buf .
	43	.Pp
	44	.Fn BIO_gets
	45	performs the BIOs "gets" operation and places the data in
	46	.Fa buf .
	47	Usually this operation will attempt to read a line of data
	48	from the BIO of maximum length
	49	.Fa len .
	50	There are exceptions to this however, for example
	51	.Fn BIO_gets
	52	on a digest BIO will calculate and return the digest
	53	and other BIOs may not support
	54	.Fn BIO_gets
	55	at all.
	56	.Pp
	57	.Fn BIO_write
	58	attempts to write
	59	.Fa len
	60	bytes from
	61	.Fa buf
	62	to BIO
	63	.Fa b .
	64	.Pp
	65	.Fn BIO_puts
	66	attempts to write a null terminated string
	67	.Fa buf
	68	to BIO
	69	.Fa b .
	70	.Sh RETURN VALUES
	71	All these functions return either the amount of data successfully
	72	read or written (if the return value is positive) or that no data
	73	was successfully read or written if the result is 0 or -1.
	74	If the return value is -2, then the operation is not implemented
	75	in the specific BIO type.
	76	.Sh NOTES
	77	A 0 or -1 return is not necessarily an indication of an error.
	78	In particular when the source/sink is non-blocking or of a certain type
	79	it may merely be an indication that no data is currently available and that
	80	the application should retry the operation later.
	81	.Pp
	82	One technique sometimes used with blocking sockets
	83	is to use a system call (such as
	84	.Xr select 2 ,
	85	.Xr poll 2
	86	or equivalent) to determine when data is available and then call
	87	.Xr read 3
	88	to read the data.
	89	The equivalent with BIOs (that is call
	90	.Xr select 2
	91	on the underlying I/O structure and then call
	92	.Fn BIO_read
	93	to read the data) should
	94	.Em not
	95	be used because a single call to
	96	.Fn BIO_read
	97	can cause several reads (and writes in the case of SSL BIOs)
	98	on the underlying I/O structure and may block as a result.
	99	Instead
	100	.Xr select 2
	101	(or equivalent) should be combined with non blocking I/O
	102	so successive reads will request a retry instead of blocking.
	103	.Pp
	104	See
	105	.Xr BIO_should_retry 3
	106	for details of how to determine the cause of a retry and other I/O issues.
	107	.Pp
	108	If the
	109	.Fn BIO_gets
	110	function is not supported by a BIO then it is possible to
	111	work around this by adding a buffering BIO
	112	.Xr BIO_f_buffer 3
	113	to the chain.
	114	.Sh SEE ALSO
	115	.Xr BIO_should_retry 3