More preliminary BIO docs...

=pod

=head1 NAME

	BIO_s_file - FILE bio.

=head1 SYNOPSIS

 #include <openssl/bio.h>

 BIO_METHOD *	BIO_s_file(void);

 BIO *BIO_new_file(const char *filename, const char *mode);

 BIO *BIO_new_fp(FILE *stream, int flags);

 BIO_set_fp(BIO *b,FILE *fp, int flags);

 BIO_get_fp(BIO *b,FILE **fpp);

 BIO_seek(BIO *b,int offset);

 int BIO_tell(BIO *b);

 int BIO_read_filename(BIO *b, char *name)

 int BIO_write_filename(BIO *b, char *name)

 int BIO_append_filename(BIO *b, char *name)

 int BIO_rw_filename(BIO *b, char *name)

=head1 DESCRIPTION

BIO_s_file() returns the BIO file method. As its name implies it

is a wrapper round the stdio FILE structure and it is a

source/sink BIO.

Calls to BIO_read() and BIO_write() read and write data to the

underlying stream. BIO_gets() and BIO_puts() are supported on file BIOs.

BIO_flush() on a file BIO calls the fflush() function on the wrapped

stream.

BIO_reset() on a file BIO calls fseek() to reset the position indicator

to the start of the file.

BIO_eof() calls feof().

Setting the BIO_CLOSE flag calls fclose() on the stream when the BIO

is freed.

BIO_new_file() creates a new file BIO with mode B<mode> the meaning

of B<mode> is the same as the stdio function fopen(). The BIO_CLOSE

flag is set on the returned BIO.

BIO_new_fp() creates a file BIO wrapping B<stream>. Flags can be:

BIO_CLOSE, BIO_NOCLOSE (the close flag) BIO_FP_TEXT (sets the underlying

stream to text mode, default is binary: this only has any effect under

Win32).

BIO_set_fp() set the fp of a file BIO to B<fp>. B<flags> has the same

meaning as in BIO_new_fp(), it is a macro.

BIO_get_fp() retrieves the fp of a file BIO, it is a macro.

BIO_seek() is a macro that sets the position pointer to B<offset> bytes

from the start of file.

BIO_tell() returns the value of the position pointer.

BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and

BIO_rw_filename() set the file BIO B<b> to use file B<name> for

reading, writing, append or read write respectively.

=head1 NOTES

When wrapping stdout, stdin or stderr the underlying stream should not

normally be closed so the BIO_NOCLOSE flag should be set.

Because the file BIO calls the underlying stdio functions any quirks

in stdio behaviour will be mirrored by the corresponding BIO.

=head1 EXAMPLES

File BIO "hello world":

 BIO *bio_out;

 bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);

 BIO_printf(bio_out, "Hello World\n");

Alternative technique:

 BIO *bio_out;

 bio_out = BIO_new(BIO_s_file());

 if(bio_out == NULL) /* Error ... */

 if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */

 BIO_printf(bio_out, "Hello World\n");

Write to a file:

 BIO *out;

 out = BIO_new_file("filename.txt", "w");

 if(!out) /* Error occurred */

 BIO_printf(out, "Hello World\n");

 BIO_free(out);

Alternative technique:

 BIO *out;

 out = BIO_new(BIO_s_file());

 if(out == NULL) /* Error ... */

 if(!BIO_read_filename(out, "filename.txt")) /* Error ... */

 BIO_printf(out, "Hello World\n");

 BIO_free(out);

=head1 RETURN VALUES

BIO_s_file() returns the file BIO method.

BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error

occurred.

BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure

(although the current implementation never return 0).

BIO_seek() returns the same value as the underlying fseek() function:

0 for success or -1 for failure.

BIO_tell() returns the current file position.

BIO_read_filename(), BIO_write_filename(),  BIO_append_filename() and

BIO_rw_filename() return 1 for success or 0 for failure.

=head1 SEE ALSO

TBA

=pod

=head1 NAME

	BIO_s_mem - memory BIO

=head1 SYNOPSIS

 #include <openssl/bio.h>

 BIO_METHOD *	BIO_s_mem(void);

 BIO_set_mem_eof_return(BIO *b,int v)

 long BIO_get_mem_data(BIO *b, char **pp)

 BIO_set_mem_buf(BIO *b,BUF_MEM *bm,int c)

 BIO_get_mem_ptr(BIO *b,BUF_MEM **pp)

 BIO *BIO_new_mem_buf(void *buf, int len);

=head1 DESCRIPTION

BIO_s_mem() return the memory BIO method function. 

A memory BIO is a source/sink BIO which uses memory for its I/O. Data

written to a memory BIO is stored in a BUF_MEM structure which is extended

as appropriate to accommodate the stored data.

Any data written to a memory BIO can be recalled by reading from it.

Unless the memory BIO is read only any data read from it is deleted from

the BIO.

Memory BIOs support BIO_gets() and BIO_puts().

If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying

BUF_MEM structure is also freed.

Calling BIO_reset() on a read write memory BIO clears any data in it. On a

read only BIO it restores the BIO to its original state and the read only

data can be read again.

BIO_eof() is true if no data is in the BIO.

BIO_ctrl_pending() returns the number of bytes currently stored.

BIO_set_mem_eof_return() sets the behaviour of memory BIO B<b> when it is

empty. If the B<v> is zero then an empty memory BIO will return EOF (that is

it will return zero and BIO_should_retry(b) will be false. If B<v> is non

zero then it will return B<v> when it is empty and it will set the read retry

flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal

positive return value B<v> should be set to a negative value, typically -1.

BIO_get_mem_data() sets B<pp> to a pointer to the start of the memory BIOs data

and returns the total amount of data available. It is implemented as a macro.

BIO_set_mem_buf() sets the internal BUF_MEM structure to B<bm> and sets the

close flag to B<c>, that is B<c> should be either BIO_CLOSE or BIO_NOCLOSE.

It is a macro.

BIO_get_mem_ptr() places the underlying BUF_MEM structure in B<pp>. It is

a macro.

BIO_new_mem_buf() creates a memory BIO using B<len> bytes of data at B<buf>,

if B<len> is -1 then the B<buf> is assumed to be null terminated and its

length is determined by B<strlen>. The BIO is set to a read only state and

as a result cannot be written to. This is useful when some data needs to be

made available from a static area of memory in the form of a BIO. The

supplied data is read directly from the supplied buffer: it is B<not> copied

first, so the supplied area of memory must be unchanged until the BIO is freed.

=head1 NOTES

Writes to memory BIOs will always succeed if memory is available: that is

their size can grow indefinitely.

Every read from a read write memory BIO will remove the data just read with

an internal copy operation, if a BIO contains a lots of data and it is

read in small chunks the operation can be very slow. The use of a read only

memory BIO avoids this problem. If the BIO must be read write then adding

a buffering BIO to the chain will speed up the process.

=head1 BUGS

There should be an option to set the maximum size of a memory BIO.

There should be a way to "rewind" a read write BIO without destroying

its contents.

The copying operation should not occur after every small read of a large BIO

to improve efficieny.

There shoy

=head1 EXAMPLE

Create a memory BIO and write some data to it:

 BIO *mem = BIO_new(BIO_s_mem());

 BIO_puts(mem, "Hello World\n"); 

Create a read only memory BIO:

 char data[] = "Hello World";

 BIO *mem;

 mem = BIO_new_mem_buf(data, -1);

Extract the BUF_MEM structure from a memory BIO and then free up the BIO:

 BUF_MEM *bptr;

 BIO_get_mem_ptr(mem, &bptr);

 BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */

 BIO_free(mem);

=head1 SEE ALSO

TBA

=pod

=head1 NAME

	BIO_should_retry, BIO_should_read, BIO_should_write - BIO retry functions

=head1 SYNOPSIS

 #include <openssl/bio.h>

 #define BIO_should_read(a)		((a)->flags & BIO_FLAGS_READ)

 #define BIO_should_write(a)		((a)->flags & BIO_FLAGS_WRITE)

 #define BIO_should_io_special(a)	((a)->flags & BIO_FLAGS_IO_SPECIAL)

 #define BIO_retry_type(a)		((a)->flags & BIO_FLAGS_RWS)

 #define BIO_should_retry(a)		((a)->flags & BIO_FLAGS_SHOULD_RETRY)

 #define BIO_FLAGS_READ		0x01

 #define BIO_FLAGS_WRITE	0x02

 #define BIO_FLAGS_IO_SPECIAL	0x04

 #define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL)

 #define BIO_FLAGS_SHOULD_RETRY	0x08

 BIO *	BIO_get_retry_BIO(BIO *bio, int *reason);

 int	BIO_get_retry_reason(BIO *bio);

=head1 DESCRIPTION

These functions determine why a BIO is not able to read or write data.

They will typically be called after a failed BIO_read() or BIO_write()

call.

BIO_should_retry() is true if the call that produced this condition

should then be retried at a later time.

If BIO_should_retry() is false then the cause is an error condition.

BIO_should_read() is true if the cause of the condition is that a BIO

needs to read data.

BIO_should_write() is true if the cause of the condition is that a BIO

needs to read data.

BIO_should_io_special() is true if some "special" condition, that is a

reason other than reading or writing is the cause of the condition.

BIO_get_retry_reason() returns a mask of the cause of a retry condition

consisting of the values B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>,

B<BIO_FLAGS_IO_SPECIAL> though current BIO types will only set one of

these (Q: is this correct?).

BIO_get_retry_BIO() determines the precise reason for the special

condition, it returns the BIO that caused this condition and if 

B<reason> is not NULL it contains the reason code. The meaning of

the reason code and the action that should be taken depends on

the type of BIO that resulted in this condition.

BIO_get_retry_reason() returns the reason for a special condition if

pass the relevant BIO, for example as returned by BIO_get_retry_BIO().

=head1 NOTES

If BIO_should_retry() returns false then the precise "error condition"

depends on the BIO type that caused it and the return code of the BIO

operation. For example if a call to BIO_read() on a socket BIO returns

0 and BIO_should_retry() is false then the cause will be that the

connection closed. A similar condition on a file BIO will mean that it

has reached EOF. Some BIO types may place additional information on

the error queue. For more details see the individual BIO type manual

pages.

If the underlying I/O structure is in a blocking mode then most BIO

types will not signal a retry condition, because the underlying I/O

calls will not. If the application knows that the BIO type will never

signal a retry then it need not call BIO_should_retry() after a failed

BIO I/O call. This is typically done with file BIOs.

The presence of an SSL BIO is an exception to this rule: it can

request a retry because the handshake process is underway (either

initially or due to a session renegotiation) even if the underlying

I/O structure (for example a socket) is in a blocking mode.

The action an application should take after a BIO has signalled that a

retry is required depends on the BIO that caused the retry.

If the underlying I/O structure is in a blocking mode then the BIO

call can be retried immediately. That is something like this can be

done:

 do {

    len = BIO_read(bio, buf, len);

 } while((len <= 0) && BIO_should_retry(bio));

While an application may retry a failed non blocking call immediately

this is likely to be very inefficient because the call is likely to

fail repeatedly until data can be processed. An application will normally

wait until the necessary condition is satisfied. How this is done depends

on the underlying I/O structure.

For example if the cause is ultimately a socket and BIO_should_read()

is true then a call to select() may be made to wait until data is

available and then retry the BIO operation. By combining the retry

conditions of several non blocking BIOs in a single select() call

it is possible to service several BIOs in a single thread. 

The cause of the retry condition may not be the same as the call that

made it: for example if BIO_write() fails BIO_should_read() can be

true. One possible reason for this is that an SSL handshake is taking

place.

Even if data is read from the underlying I/O structure this does not

imply that the next BIO I/O call will succeed. For example if an

encryption BIO reads only a fraction of a block it will not be

able to pass any data to the application until a complete block has

been read.

It is possible for a BIO to block indefinitely if the underlying I/O

structure cannot process the data. This depends on the behaviour of

the platforms I/O functions. This is often not desirable: one solution

is to use non blocking I/O and use a timeout on the select() (or

equivalent) call.

=head1 BUGS

The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O:

that is they cannot retry after a partial read or write. This is usually

worked around by only passing the relevant data to ASN1 functions when

the entire structure can be read or written.

=head1 SEE ALSO

TBA