From 9a3026fb0a89a15ea2def3629cc13a69f1fc678c Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Mon, 16 Feb 2015 16:42:14 +0000 Subject: third batch of perlpod(1) to mdoc(7) conversion --- src/lib/libssl/src/doc/crypto/BIO_push.pod | 67 -------- src/lib/libssl/src/doc/crypto/BIO_read.pod | 66 ------- src/lib/libssl/src/doc/crypto/BIO_s_accept.pod | 189 -------------------- src/lib/libssl/src/doc/crypto/BIO_s_bio.pod | 185 -------------------- src/lib/libssl/src/doc/crypto/BIO_s_connect.pod | 191 --------------------- src/lib/libssl/src/doc/crypto/BIO_s_fd.pod | 91 ---------- src/lib/libssl/src/doc/crypto/BIO_s_file.pod | 150 ---------------- src/lib/libssl/src/doc/crypto/BIO_s_mem.pod | 112 ------------ src/lib/libssl/src/doc/crypto/BIO_s_null.pod | 35 ---- src/lib/libssl/src/doc/crypto/BIO_s_socket.pod | 61 ------- src/lib/libssl/src/doc/crypto/BIO_set_callback.pod | 105 ----------- src/lib/libssl/src/doc/crypto/BIO_should_retry.pod | 112 ------------ 12 files changed, 1364 deletions(-) delete mode 100644 src/lib/libssl/src/doc/crypto/BIO_push.pod delete mode 100644 src/lib/libssl/src/doc/crypto/BIO_read.pod delete mode 100644 src/lib/libssl/src/doc/crypto/BIO_s_accept.pod delete mode 100644 src/lib/libssl/src/doc/crypto/BIO_s_bio.pod delete mode 100644 src/lib/libssl/src/doc/crypto/BIO_s_connect.pod delete mode 100644 src/lib/libssl/src/doc/crypto/BIO_s_fd.pod delete mode 100644 src/lib/libssl/src/doc/crypto/BIO_s_file.pod delete mode 100644 src/lib/libssl/src/doc/crypto/BIO_s_mem.pod delete mode 100644 src/lib/libssl/src/doc/crypto/BIO_s_null.pod delete mode 100644 src/lib/libssl/src/doc/crypto/BIO_s_socket.pod delete mode 100644 src/lib/libssl/src/doc/crypto/BIO_set_callback.pod delete mode 100644 src/lib/libssl/src/doc/crypto/BIO_should_retry.pod (limited to 'src/lib/libssl') diff --git a/src/lib/libssl/src/doc/crypto/BIO_push.pod b/src/lib/libssl/src/doc/crypto/BIO_push.pod deleted file mode 100644 index 39c964b272..0000000000 --- a/src/lib/libssl/src/doc/crypto/BIO_push.pod +++ /dev/null @@ -1,67 +0,0 @@ -=pod - -=head1 NAME - -BIO_push, BIO_pop - add and remove BIOs from a chain. - -=head1 SYNOPSIS - - #include - - BIO * BIO_push(BIO *b,BIO *append); - BIO * BIO_pop(BIO *b); - -=head1 DESCRIPTION - -The BIO_push() function appends the BIO B to B, and returns -B. - -BIO_pop() removes the BIO B from a chain and returns the next BIO -in the chain, or NULL if there is no next BIO. The removed BIO then -becomes a single BIO with no association with the original chain, -it can thus be freed or attached to a different chain. - -=head1 NOTES - -The names of these functions are perhaps a little misleading. BIO_push() -joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain, -the deleted BIO does not need to be at the end of a chain. - -The process of calling BIO_push() and BIO_pop() on a BIO may have additional -consequences (a control call is made to the affected BIOs) any effects will -be noted in the descriptions of individual BIOs. - -=head1 EXAMPLES - -For these examples suppose B and B are digest BIOs, B is -a base64 BIO and B is a file BIO. - -If the call: - - BIO_push(b64, f); - -is made then the new chain will be B. After making the calls - - BIO_push(md2, b64); - BIO_push(md1, md2); - -the new chain is B. Data written to B will be digested -by B and B, B encoded and written to B. - -It should be noted that reading causes data to pass in the reverse -direction, that is data is read from B, base64 B and digested -by B and B. If the call: - - BIO_pop(md2); - -The call will return B and the new chain will be B; data can -be written to B as before. - -=head1 RETURN VALUES - -BIO_push() returns the beginning of the chain, B. - -BIO_pop() returns the next BIO in the chain, or NULL if there is no next -BIO. - -=cut diff --git a/src/lib/libssl/src/doc/crypto/BIO_read.pod b/src/lib/libssl/src/doc/crypto/BIO_read.pod deleted file mode 100644 index e527bff8d0..0000000000 --- a/src/lib/libssl/src/doc/crypto/BIO_read.pod +++ /dev/null @@ -1,66 +0,0 @@ -=pod - -=head1 NAME - -BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions - -=head1 SYNOPSIS - - #include - - int BIO_read(BIO *b, void *buf, int len); - int BIO_gets(BIO *b, char *buf, int size); - int BIO_write(BIO *b, const void *buf, int len); - int BIO_puts(BIO *b, const char *buf); - -=head1 DESCRIPTION - -BIO_read() attempts to read B bytes from BIO B and places -the data in B. - -BIO_gets() performs the BIOs "gets" operation and places the data -in B. Usually this operation will attempt to read a line of data -from the BIO of maximum length B. There are exceptions to this -however, for example BIO_gets() on a digest BIO will calculate and -return the digest and other BIOs may not support BIO_gets() at all. - -BIO_write() attempts to write B bytes from B to BIO B. - -BIO_puts() attempts to write a null terminated string B to BIO B. - -=head1 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. - -=head1 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. - -One technique sometimes used with blocking sockets is to use a system call -(such as select(), poll() or equivalent) to determine when data is available -and then call read() to read the data. The equivalent with BIOs (that is call -select() on the underlying I/O structure and then call BIO_read() to -read the data) should B be used because a single call to 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 select() (or equivalent) -should be combined with non blocking I/O so successive reads will request -a retry instead of blocking. - -See L for details of how to -determine the cause of a retry and other I/O issues. - -If the BIO_gets() function is not supported by a BIO then it possible to -work around this by adding a buffering BIO L -to the chain. - -=head1 SEE ALSO - -L - -=cut diff --git a/src/lib/libssl/src/doc/crypto/BIO_s_accept.pod b/src/lib/libssl/src/doc/crypto/BIO_s_accept.pod deleted file mode 100644 index 5729d38193..0000000000 --- a/src/lib/libssl/src/doc/crypto/BIO_s_accept.pod +++ /dev/null @@ -1,189 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port, BIO_new_accept, -BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode, -BIO_get_bind_mode, BIO_do_accept - accept BIO - -=head1 SYNOPSIS - - #include - - BIO_METHOD *BIO_s_accept(void); - - long BIO_set_accept_port(BIO *b, char *name); - char *BIO_get_accept_port(BIO *b); - - BIO *BIO_new_accept(char *host_port); - - long BIO_set_nbio_accept(BIO *b, int n); - long BIO_set_accept_bios(BIO *b, char *bio); - - long BIO_set_bind_mode(BIO *b, long mode); - long BIO_get_bind_mode(BIO *b, long dummy); - - #define BIO_BIND_NORMAL 0 - #define BIO_BIND_REUSEADDR_IF_UNUSED 1 - #define BIO_BIND_REUSEADDR 2 - - int BIO_do_accept(BIO *b); - -=head1 DESCRIPTION - -BIO_s_accept() returns the accept BIO method. This is a wrapper -round the platform's TCP/IP socket accept routines. - -Using accept BIOs, TCP/IP connections can be accepted and data -transferred using only BIO routines. In this way any platform -specific operations are hidden by the BIO abstraction. - -Read and write operations on an accept BIO will perform I/O -on the underlying connection. If no connection is established -and the port (see below) is set up properly then the BIO -waits for an incoming connection. - -Accept BIOs support BIO_puts() but not BIO_gets(). - -If the close flag is set on an accept BIO then any active -connection on that chain is shutdown and the socket closed when -the BIO is freed. - -Calling BIO_reset() on a accept BIO will close any active -connection and reset the BIO into a state where it awaits another -incoming connection. - -BIO_get_fd() and BIO_set_fd() can be called to retrieve or set -the accept socket. See L - -BIO_set_accept_port() uses the string B to set the accept -port. The port is represented as a string of the form "host:port", -where "host" is the interface to use and "port" is the port. -Either or both values can be "*" which is interpreted as meaning -any interface or port respectively. "port" has the same syntax -as the port specified in BIO_set_conn_port() for connect BIOs, -that is it can be a numerical port string or a string to lookup -using getservbyname() and a string table. - -BIO_new_accept() combines BIO_new() and BIO_set_accept_port() into -a single call: that is it creates a new accept BIO with port -B. - -BIO_set_nbio_accept() sets the accept socket to blocking mode -(the default) if B is 0 or non blocking mode if B is 1. - -BIO_set_accept_bios() can be used to set a chain of BIOs which -will be duplicated and prepended to the chain when an incoming -connection is received. This is useful if, for example, a -buffering or SSL BIO is required for each connection. The -chain of BIOs must not be freed after this call, they will -be automatically freed when the accept BIO is freed. - -BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve -the current bind mode. If BIO_BIND_NORMAL (the default) is set -then another socket cannot be bound to the same port. If -BIO_BIND_REUSEADDR is set then other sockets can bind to the -same port. If BIO_BIND_REUSEADDR_IF_UNUSED is set then and -attempt is first made to use BIO_BIN_NORMAL, if this fails -and the port is not in use then a second attempt is made -using BIO_BIND_REUSEADDR. - -BIO_do_accept() serves two functions. When it is first -called, after the accept BIO has been setup, it will attempt -to create the accept socket and bind an address to it. Second -and subsequent calls to BIO_do_accept() will await an incoming -connection, or request a retry in non blocking mode. - -=head1 NOTES - -When an accept BIO is at the end of a chain it will await an -incoming connection before processing I/O calls. When an accept -BIO is not at then end of a chain it passes I/O calls to the next -BIO in the chain. - -When a connection is established a new socket BIO is created for -the connection and appended to the chain. That is the chain is now -accept->socket. This effectively means that attempting I/O on -an initial accept socket will await an incoming connection then -perform I/O on it. - -If any additional BIOs have been set using BIO_set_accept_bios() -then they are placed between the socket and the accept BIO, -that is the chain will be accept->otherbios->socket. - -If a server wishes to process multiple connections (as is normally -the case) then the accept BIO must be made available for further -incoming connections. This can be done by waiting for a connection and -then calling: - - connection = BIO_pop(accept); - -After this call B will contain a BIO for the recently -established connection and B will now be a single BIO -again which can be used to await further incoming connections. -If no further connections will be accepted the B can -be freed using BIO_free(). - -If only a single connection will be processed it is possible to -perform I/O using the accept BIO itself. This is often undesirable -however because the accept BIO will still accept additional incoming -connections. This can be resolved by using BIO_pop() (see above) -and freeing up the accept BIO after the initial connection. - -If the underlying accept socket is non-blocking and BIO_do_accept() is -called to await an incoming connection it is possible for -BIO_should_io_special() with the reason BIO_RR_ACCEPT. If this happens -then it is an indication that an accept attempt would block: the application -should take appropriate action to wait until the underlying socket has -accepted a connection and retry the call. - -BIO_set_accept_port(), BIO_get_accept_port(), BIO_set_nbio_accept(), -BIO_set_accept_bios(), BIO_set_bind_mode(), BIO_get_bind_mode() and -BIO_do_accept() are macros. - -=head1 EXAMPLE - -This example accepts two connections on port 4444, sends messages -down each and finally closes both down. - - BIO *abio, *cbio, *cbio2; - ERR_load_crypto_strings(); - abio = BIO_new_accept("4444"); - - /* First call to BIO_accept() sets up accept BIO */ - if (BIO_do_accept(abio) <= 0) { - fprintf(stderr, "Error setting up accept\n"); - ERR_print_errors_fp(stderr); - exit(0); - } - - /* Wait for incoming connection */ - if (BIO_do_accept(abio) <= 0) { - fprintf(stderr, "Error accepting connection\n"); - ERR_print_errors_fp(stderr); - exit(0); - } - fprintf(stderr, "Connection 1 established\n"); - /* Retrieve BIO for connection */ - cbio = BIO_pop(abio); - BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n"); - fprintf(stderr, "Sent out data on connection 1\n"); - /* Wait for another connection */ - if (BIO_do_accept(abio) <= 0) { - fprintf(stderr, "Error accepting connection\n"); - ERR_print_errors_fp(stderr); - exit(0); - } - fprintf(stderr, "Connection 2 established\n"); - /* Close accept BIO to refuse further connections */ - cbio2 = BIO_pop(abio); - BIO_free(abio); - BIO_puts(cbio2, "Connection 2: Sending out Data on second\n"); - fprintf(stderr, "Sent out data on connection 2\n"); - - BIO_puts(cbio, "Connection 1: Second connection established\n"); - /* Close the two established connections */ - BIO_free(cbio); - BIO_free(cbio2); - -=cut diff --git a/src/lib/libssl/src/doc/crypto/BIO_s_bio.pod b/src/lib/libssl/src/doc/crypto/BIO_s_bio.pod deleted file mode 100644 index 61ded32a02..0000000000 --- a/src/lib/libssl/src/doc/crypto/BIO_s_bio.pod +++ /dev/null @@ -1,185 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr, -BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair, -BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request, -BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO - -=head1 SYNOPSIS - - #include - - BIO_METHOD *BIO_s_bio(void); - - #define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2) - #define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL) - - #define BIO_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL) - - #define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,BIO_C_SET_WRITE_BUF_SIZE,size,NULL) - #define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL) - - int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2); - - #define BIO_get_write_guarantee(b) (int)BIO_ctrl(b,BIO_C_GET_WRITE_GUARANTEE,0,NULL) - size_t BIO_ctrl_get_write_guarantee(BIO *b); - - #define BIO_get_read_request(b) (int)BIO_ctrl(b,BIO_C_GET_READ_REQUEST,0,NULL) - size_t BIO_ctrl_get_read_request(BIO *b); - - int BIO_ctrl_reset_read_request(BIO *b); - -=head1 DESCRIPTION - -BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of -source/sink BIOs where data written to either half of the pair is buffered and -can be read from the other half. Both halves must usually by handled by the -same application thread since no locking is done on the internal data -structures. - -Since BIO chains typically end in a source/sink BIO it is possible to make this -one half of a BIO pair and have all the data processed by the chain under -application control. - -One typical use of BIO pairs is to place TLS/SSL I/O under application control, -this can be used when the application wishes to use a non standard transport -for TLS/SSL or the normal socket routines are inappropriate. - -Calls to BIO_read() will read data from the buffer or request a retry if no -data is available. - -Calls to BIO_write() will place data in the buffer or request a retry if the -buffer is full. - -The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to -determine the amount of pending data in the read or write buffer. - -BIO_reset() clears any data in the write buffer. - -BIO_make_bio_pair() joins two separate BIOs into a connected pair. - -BIO_destroy_pair() destroys the association between two connected BIOs. Freeing -up any half of the pair will automatically destroy the association. - -BIO_shutdown_wr() is used to close down a BIO B. After this call no further -writes on BIO B are allowed (they will return an error). Reads on the other -half of the pair will return any pending data or EOF when all pending data has -been read. - -BIO_set_write_buf_size() sets the write buffer size of BIO B to B. -If the size is not initialized a default value is used. This is currently -17K, sufficient for a maximum size TLS record. - -BIO_get_write_buf_size() returns the size of the write buffer. - -BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and -BIO_set_write_buf_size() to create a connected pair of BIOs B, B -with write buffer sizes B and B. If either size is -zero then the default size is used. BIO_new_bio_pair() does not check whether -B or B do point to some other BIO, the values are overwritten, -BIO_free() is not called. - -BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum -length of data that can be currently written to the BIO. Writes larger than -this value will return a value from BIO_write() less than the amount requested -or if the buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a -function whereas BIO_get_write_guarantee() is a macro. - -BIO_get_read_request() and BIO_ctrl_get_read_request() return the -amount of data requested, or the buffer size if it is less, if the -last read attempt at the other half of the BIO pair failed due to an -empty buffer. This can be used to determine how much data should be -written to the BIO so the next read will succeed: this is most useful -in TLS/SSL applications where the amount of data read is usually -meaningful rather than just a buffer size. After a successful read -this call will return zero. It also will return zero once new data -has been written satisfying the read request or part of it. -Note that BIO_get_read_request() never returns an amount larger -than that returned by BIO_get_write_guarantee(). - -BIO_ctrl_reset_read_request() can also be used to reset the value returned by -BIO_get_read_request() to zero. - -=head1 NOTES - -Both halves of a BIO pair should be freed. That is even if one half is implicit -freed due to a BIO_free_all() or SSL_free() call the other half needs to be -freed. - -When used in bidirectional applications (such as TLS/SSL) care should be taken -to flush any data in the write buffer. This can be done by calling -BIO_pending() on the other half of the pair and, if any data is pending, -reading it and sending it to the underlying transport. This must be done before -any normal processing (such as calling select() ) due to a request and -BIO_should_read() being true. - -To see why this is important consider a case where a request is sent using -BIO_write() and a response read with BIO_read(), this can occur during an -TLS/SSL handshake for example. BIO_write() will succeed and place data in the -write buffer. BIO_read() will initially fail and BIO_should_read() will be -true. If the application then waits for data to be available on the underlying -transport before flushing the write buffer it will never succeed because the -request was never sent! - -=head1 RETURN VALUES - -BIO_new_bio_pair() returns 1 on success, with the new BIOs available in -B and B, or 0 on failure, with NULL pointers stored into the -locations for B and B. Check the error stack for more information. - -[TODO: More return values need to be added here] - -=head1 EXAMPLE - -The BIO pair can be used to have full control over the network access of an -application. The application can call select() on the socket as required -without having to go through the SSL-interface. - - BIO *internal_bio, *network_bio; - ... - BIO_new_bio_pair(internal_bio, 0, network_bio, 0); - SSL_set_bio(ssl, internal_bio, internal_bio); - SSL_operations(); - ... - - application | TLS-engine - | | - +----------> SSL_operations() - | /\ || - | || \/ - | BIO-pair (internal_bio) - +----------< BIO-pair (network_bio) - | | - socket | - - ... - SSL_free(ssl); /* implicitly frees internal_bio */ - BIO_free(network_bio); - ... - -As the BIO pair will only buffer the data and never directly access the -connection, it behaves non-blocking and will return as soon as the write -buffer is full or the read buffer is drained. Then the application has to -flush the write buffer and/or fill the read buffer. - -Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO -and must be transfered to the network. Use BIO_ctrl_get_read_request() to -find out, how many bytes must be written into the buffer before the -SSL_operation() can successfully be continued. - -=head1 WARNING - -As the data is buffered, SSL_operation() may return with a ERROR_SSL_WANT_READ -condition, but there is still data in the write buffer. An application must -not rely on the error value of SSL_operation() but must assure that the -write buffer is always flushed first. Otherwise a deadlock may occur as -the peer might be waiting for the data before being able to continue. - -=head1 SEE ALSO - -L, L, L, -L, L - -=cut diff --git a/src/lib/libssl/src/doc/crypto/BIO_s_connect.pod b/src/lib/libssl/src/doc/crypto/BIO_s_connect.pod deleted file mode 100644 index 45832e52f3..0000000000 --- a/src/lib/libssl/src/doc/crypto/BIO_s_connect.pod +++ /dev/null @@ -1,191 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port, -BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname, -BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port, -BIO_set_nbio, BIO_do_connect - connect BIO - -=head1 SYNOPSIS - - #include - - BIO_METHOD * BIO_s_connect(void); - - BIO *BIO_new_connect(char *name); - - long BIO_set_conn_hostname(BIO *b, char *name); - long BIO_set_conn_port(BIO *b, char *port); - long BIO_set_conn_ip(BIO *b, char *ip); - long BIO_set_conn_int_port(BIO *b, char *port); - char *BIO_get_conn_hostname(BIO *b); - char *BIO_get_conn_port(BIO *b); - char *BIO_get_conn_ip(BIO *b, dummy); - long BIO_get_conn_int_port(BIO *b, int port); - - long BIO_set_nbio(BIO *b, long n); - - int BIO_do_connect(BIO *b); - -=head1 DESCRIPTION - -BIO_s_connect() returns the connect BIO method. This is a wrapper -round the platform's TCP/IP socket connection routines. - -Using connect BIOs, TCP/IP connections can be made and data -transferred using only BIO routines. In this way any platform -specific operations are hidden by the BIO abstraction. - -Read and write operations on a connect BIO will perform I/O -on the underlying connection. If no connection is established -and the port and hostname (see below) is set up properly then -a connection is established first. - -Connect BIOs support BIO_puts() but not BIO_gets(). - -If the close flag is set on a connect BIO then any active -connection is shutdown and the socket closed when the BIO -is freed. - -Calling BIO_reset() on a connect BIO will close any active -connection and reset the BIO into a state where it can connect -to the same host again. - -BIO_get_fd() places the underlying socket in B if it is not NULL, -it also returns the socket . If B is not NULL it should be of -type (int *). - -BIO_set_conn_hostname() uses the string B to set the hostname. -The hostname can be an IP address. The hostname can also include the -port in the form hostname:port . It is also acceptable to use the -form "hostname/any/other/path" or "hostname:port/any/other/path". - -BIO_set_conn_port() sets the port to B. B can be the -numerical form or a string such as "http". A string will be looked -up first using getservbyname() on the host platform but if that -fails a standard table of port names will be used. Currently the -list is http, telnet, socks, https, ssl, ftp, gopher and wais. - -BIO_set_conn_ip() sets the IP address to B using binary form, -that is four bytes specifying the IP address in big-endian form. - -BIO_set_conn_int_port() sets the port using B. B should -be of type (int *). - -BIO_get_conn_hostname() returns the hostname of the connect BIO or -NULL if the BIO is initialized but no hostname is set. -This return value is an internal pointer which should not be modified. - -BIO_get_conn_port() returns the port as a string. - -BIO_get_conn_ip() returns the IP address in binary form. - -BIO_get_conn_int_port() returns the port as an int. - -BIO_set_nbio() sets the non blocking I/O flag to B. If B is -zero then blocking I/O is set. If B is 1 then non blocking I/O -is set. Blocking I/O is the default. The call to BIO_set_nbio() -should be made before the connection is established because -non blocking I/O is set during the connect process. - -BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into -a single call: that is it creates a new connect BIO with B. - -BIO_do_connect() attempts to connect the supplied BIO. It returns 1 -if the connection was established successfully. A zero or negative -value is returned if the connection could not be established, the -call BIO_should_retry() should be used for non blocking connect BIOs -to determine if the call should be retried. - -=head1 NOTES - -If blocking I/O is set then a non positive return value from any -I/O call is caused by an error condition, although a zero return -will normally mean that the connection was closed. - -If the port name is supplied as part of the host name then this will -override any value set with BIO_set_conn_port(). This may be undesirable -if the application does not wish to allow connection to arbitrary -ports. This can be avoided by checking for the presence of the ':' -character in the passed hostname and either indicating an error or -truncating the string at that point. - -The values returned by BIO_get_conn_hostname(), BIO_get_conn_port(), -BIO_get_conn_ip() and BIO_get_conn_int_port() are updated when a -connection attempt is made. Before any connection attempt the values -returned are those set by the application itself. - -Applications do not have to call BIO_do_connect() but may wish to do -so to separate the connection process from other I/O processing. - -If non blocking I/O is set then retries will be requested as appropriate. - -It addition to BIO_should_read() and BIO_should_write() it is also -possible for BIO_should_io_special() to be true during the initial -connection process with the reason BIO_RR_CONNECT. If this is returned -then this is an indication that a connection attempt would block, -the application should then take appropriate action to wait until -the underlying socket has connected and retry the call. - -BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip(), -BIO_set_conn_int_port(), BIO_get_conn_hostname(), BIO_get_conn_port(), -BIO_get_conn_ip(), BIO_get_conn_int_port(), BIO_set_nbio() and -BIO_do_connect() are macros. - -=head1 RETURN VALUES - -BIO_s_connect() returns the connect BIO method. - -BIO_get_fd() returns the socket or -1 if the BIO has not -been initialized. - -BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and -BIO_set_conn_int_port() always return 1. - -BIO_get_conn_hostname() returns the connected hostname or NULL is -none was set. - -BIO_get_conn_port() returns a string representing the connected -port or NULL if not set. - -BIO_get_conn_ip() returns a pointer to the connected IP address in -binary form or all zeros if not set. - -BIO_get_conn_int_port() returns the connected port or 0 if none was -set. - -BIO_set_nbio() always returns 1. - -BIO_do_connect() returns 1 if the connection was successfully -established and 0 or -1 if the connection failed. - -=head1 EXAMPLE - -This is example connects to a webserver on the local host and attempts -to retrieve a page and copy the result to standard output. - - - BIO *cbio, *out; - int len; - char tmpbuf[1024]; - - ERR_load_crypto_strings(); - cbio = BIO_new_connect("localhost:http"); - out = BIO_new_fp(stdout, BIO_NOCLOSE); - if (BIO_do_connect(cbio) <= 0) { - fprintf(stderr, "Error connecting to server\n"); - ERR_print_errors_fp(stderr); - /* whatever ... */ - } - BIO_puts(cbio, "GET / HTTP/1.0\n\n"); - for(;;) { - len = BIO_read(cbio, tmpbuf, 1024); - if (len <= 0) - break; - BIO_write(out, tmpbuf, len); - } - BIO_free(cbio); - BIO_free(out); - -=cut diff --git a/src/lib/libssl/src/doc/crypto/BIO_s_fd.pod b/src/lib/libssl/src/doc/crypto/BIO_s_fd.pod deleted file mode 100644 index 22b7575ba0..0000000000 --- a/src/lib/libssl/src/doc/crypto/BIO_s_fd.pod +++ /dev/null @@ -1,91 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO - -=head1 SYNOPSIS - - #include - - BIO_METHOD * BIO_s_fd(void); - - #define BIO_set_fd(b,fd,c) BIO_int_ctrl(b,BIO_C_SET_FD,c,fd) - #define BIO_get_fd(b,c) BIO_ctrl(b,BIO_C_GET_FD,0,(char *)c) - - BIO *BIO_new_fd(int fd, int close_flag); - -=head1 DESCRIPTION - -BIO_s_fd() returns the file descriptor BIO method. This is a wrapper -round the platforms file descriptor routines such as read() and write(). - -BIO_read() and BIO_write() read or write the underlying descriptor. -BIO_puts() is supported but BIO_gets() is not. - -If the close flag is set then then close() is called on the underlying -file descriptor when the BIO is freed. - -BIO_reset() attempts to change the file pointer to the start of file -using lseek(fd, 0, 0). - -BIO_seek() sets the file pointer to position B from start of file -using lseek(fd, ofs, 0). - -BIO_tell() returns the current file position by calling lseek(fd, 0, 1). - -BIO_set_fd() sets the file descriptor of BIO B to B and the close -flag to B. - -BIO_get_fd() places the file descriptor in B if it is not NULL, it also -returns the file descriptor. If B is not NULL it should be of type -(int *). - -BIO_new_fd() returns a file descriptor BIO using B and B. - -=head1 NOTES - -The behaviour of BIO_read() and BIO_write() depends on the behavior of the -platforms read() and write() 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 L and -L manual pages. - -File descriptor BIOs should not be used for socket I/O. Use socket BIOs -instead. - -=head1 RETURN VALUES - -BIO_s_fd() returns the file descriptor BIO method. - -BIO_reset() returns zero for success and -1 if an error occurred. -BIO_seek() and BIO_tell() return the current file position or -1 -is an error occurred. These values reflect the underlying lseek() -behaviour. - -BIO_set_fd() always returns 1. - -BIO_get_fd() returns the file descriptor or -1 if the BIO has not -been initialized. - -BIO_new_fd() returns the newly allocated BIO or NULL is an error -occurred. - -=head1 EXAMPLE - -This is a file descriptor BIO version of "Hello World": - - BIO *out; - out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE); - BIO_printf(out, "Hello World\n"); - BIO_free(out); - -=head1 SEE ALSO - -L, L, -L, L, -L, L, -L, L, -L, L - -=cut diff --git a/src/lib/libssl/src/doc/crypto/BIO_s_file.pod b/src/lib/libssl/src/doc/crypto/BIO_s_file.pod deleted file mode 100644 index 0c9cb824da..0000000000 --- a/src/lib/libssl/src/doc/crypto/BIO_s_file.pod +++ /dev/null @@ -1,150 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp, -BIO_read_filename, BIO_write_filename, BIO_append_filename, -BIO_rw_filename - FILE bio - -=head1 SYNOPSIS - - #include - - 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); - - 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() attempts to change the file pointer to the start of file -using fseek(stream, 0, 0). - -BIO_seek() sets the file pointer to position B from start of file -using fseek(stream, ofs, 0). - -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 the meaning -of B 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. 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. B 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 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 to use file B 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. - -On Windows BIO_new_files reserves for the filename argument to be -UTF-8 encoded. In other words if you have to make it work in multi- -lingual environment, encode file names in UTF-8. - -=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_write_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 BUGS - -BIO_reset() and BIO_seek() are implemented using fseek() on the underlying -stream. The return value for fseek() is 0 for success or -1 if an error -occurred this differs from other types of BIO which will typically return -1 for success and a non positive value if an error occurred. - -=head1 SEE ALSO - -L, L, -L, L, -L, -L, L, -L, L, -L, L - -=cut diff --git a/src/lib/libssl/src/doc/crypto/BIO_s_mem.pod b/src/lib/libssl/src/doc/crypto/BIO_s_mem.pod deleted file mode 100644 index 4541b3fc55..0000000000 --- a/src/lib/libssl/src/doc/crypto/BIO_s_mem.pod +++ /dev/null @@ -1,112 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf, -BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO - -=head1 SYNOPSIS - - #include - - 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 when it is -empty. If the B 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 is non -zero then it will return B 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 should be set to a negative value, typically -1. - -BIO_get_mem_data() sets B 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 and sets the -close flag to B, that is B should be either BIO_CLOSE or BIO_NOCLOSE. -It is a macro. - -BIO_get_mem_ptr() places the underlying BUF_MEM structure in B. It is -a macro. - -BIO_new_mem_buf() creates a memory BIO using B bytes of data at B, -if B is -1 then the B is assumed to be null terminated and its -length is determined by B. 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 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 lot 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 efficiency. - -=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); - -=cut diff --git a/src/lib/libssl/src/doc/crypto/BIO_s_null.pod b/src/lib/libssl/src/doc/crypto/BIO_s_null.pod deleted file mode 100644 index 9f7d4ac46a..0000000000 --- a/src/lib/libssl/src/doc/crypto/BIO_s_null.pod +++ /dev/null @@ -1,35 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_null - null data sink - -=head1 SYNOPSIS - - #include - - BIO_METHOD * BIO_s_null(void); - -=head1 DESCRIPTION - -BIO_s_null() returns the null sink BIO method. Data written to -the null sink is discarded, reads return EOF. - -=head1 NOTES - -A null sink BIO behaves in a similar manner to the Unix /dev/null -device. - -A null bio can be placed on the end of a chain to discard any data -passed through it. - -A null sink is useful if, for example, an application wishes to digest some -data by writing through a digest bio but not send the digested data anywhere. -Since a BIO chain must normally include a source/sink BIO this can be achieved -by adding a null sink BIO to the end of the chain - -=head1 RETURN VALUES - -BIO_s_null() returns the null sink BIO method. - -=cut diff --git a/src/lib/libssl/src/doc/crypto/BIO_s_socket.pod b/src/lib/libssl/src/doc/crypto/BIO_s_socket.pod deleted file mode 100644 index 402aff26e2..0000000000 --- a/src/lib/libssl/src/doc/crypto/BIO_s_socket.pod +++ /dev/null @@ -1,61 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_socket, BIO_new_socket - socket BIO - -=head1 SYNOPSIS - - #include - - BIO_METHOD *BIO_s_socket(void); - - long BIO_set_fd(BIO *b, int fd, long close_flag); - long BIO_get_fd(BIO *b, int *c); - - BIO *BIO_new_socket(int sock, int close_flag); - -=head1 DESCRIPTION - -BIO_s_socket() returns the socket BIO method. This is a wrapper -round the platform's socket routines. - -BIO_read() and BIO_write() read or write the underlying socket. -BIO_puts() is supported but BIO_gets() is not. - -If the close flag is set then the socket is shut down and closed -when the BIO is freed. - -BIO_set_fd() sets the socket of BIO B to B and the close -flag to B. - -BIO_get_fd() places the socket in B if it is not NULL, it also -returns the socket. If B is not NULL it should be of type (int *). - -BIO_new_socket() returns a socket BIO using B and B. - -=head1 NOTES - -Socket BIOs also support any relevant functionality of file descriptor -BIOs. - -The reason for having separate file descriptor and socket BIOs is that on some -platforms sockets are not file descriptors and use distinct I/O routines, -Windows is one such platform. Any code mixing the two will not work on -all platforms. - -BIO_set_fd() and BIO_get_fd() are macros. - -=head1 RETURN VALUES - -BIO_s_socket() returns the socket BIO method. - -BIO_set_fd() always returns 1. - -BIO_get_fd() returns the socket or -1 if the BIO has not been -initialized. - -BIO_new_socket() returns the newly allocated BIO or NULL is an error -occurred. - -=cut diff --git a/src/lib/libssl/src/doc/crypto/BIO_set_callback.pod b/src/lib/libssl/src/doc/crypto/BIO_set_callback.pod deleted file mode 100644 index 8e4e5900d9..0000000000 --- a/src/lib/libssl/src/doc/crypto/BIO_set_callback.pod +++ /dev/null @@ -1,105 +0,0 @@ -=pod - -=head1 NAME - -BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg, -BIO_debug_callback - BIO callback functions - -=head1 SYNOPSIS - - #include - - #define BIO_set_callback(b,cb) ((b)->callback=(cb)) - #define BIO_get_callback(b) ((b)->callback) - #define BIO_set_callback_arg(b,arg) ((b)->cb_arg=(char *)(arg)) - #define BIO_get_callback_arg(b) ((b)->cb_arg) - - long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi, - long argl,long ret); - - typedef long (*callback)(BIO *b, int oper, const char *argp, - int argi, long argl, long retvalue); - -=head1 DESCRIPTION - -BIO_set_callback() and BIO_get_callback() set and retrieve the BIO callback, -they are both macros. The callback is called during most high level BIO -operations. It can be used for debugging purposes to trace operations on -a BIO or to modify its operation. - -BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be -used to set and retrieve an argument for use in the callback. - -BIO_debug_callback() is a standard debugging callback which prints -out information relating to each BIO operation. If the callback -argument is set if is interpreted as a BIO to send the information -to, otherwise stderr is used. - -callback() is the callback function itself. The meaning of each -argument is described below. - -The BIO the callback is attached to is passed in B. - -B is set to the operation being performed. For some operations -the callback is called twice, once before and once after the actual -operation, the latter case has B or'ed with BIO_CB_RETURN. - -The meaning of the arguments B, B and B depends on -the value of B, that is the operation being performed. - -B is the return value that would be returned to the -application if no callback were present. The actual value returned -is the return value of the callback itself. In the case of callbacks -called before the actual BIO operation 1 is placed in retvalue, if -the return value is not positive it will be immediately returned to -the application and the BIO operation will not be performed. - -The callback should normally simply return B when it has -finished processing, unless if specifically wishes to modify the -value returned to the application. - -=head1 CALLBACK OPERATIONS - -=over 4 - -=item B - -callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before the -free operation. - -=item B - -callback(b, BIO_CB_READ, out, outl, 0L, 1L) is called before -the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue) -after. - -=item B - -callback(b, BIO_CB_WRITE, in, inl, 0L, 1L) is called before -the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue) -after. - -=item B - -callback(b, BIO_CB_GETS, out, outl, 0L, 1L) is called before the operation and -callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue) after. - -=item B - -callback(b, BIO_CB_WRITE, in, 0, 0L, 1L) is called before -the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue) -after. - -=item B - -callback(b,BIO_CB_CTRL,parg,cmd,larg,1L) is called before the call and -callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after. - -=back - -=head1 EXAMPLE - -The BIO_debug_callback() function is a good example, its source is -in crypto/bio/bio_cb.c - -=cut diff --git a/src/lib/libssl/src/doc/crypto/BIO_should_retry.pod b/src/lib/libssl/src/doc/crypto/BIO_should_retry.pod deleted file mode 100644 index 3b7fc39997..0000000000 --- a/src/lib/libssl/src/doc/crypto/BIO_should_retry.pod +++ /dev/null @@ -1,112 +0,0 @@ -=pod - -=head1 NAME - -BIO_should_retry, BIO_should_read, BIO_should_write, -BIO_should_io_special, BIO_retry_type, -BIO_get_retry_BIO, BIO_get_retry_reason - BIO retry functions - -=head1 SYNOPSIS - - #include - - #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_retry_type() returns a mask of the cause of a retry condition -consisting of the values B, B, -B though current BIO types will only set one of -these. - -BIO_get_retry_BIO() determines the precise reason for the special -condition, it returns the BIO that caused this condition and if -B 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 -passed 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 almost all current -BIO types will not request a retry, 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. - -SSL BIOs are the only current exception to this rule: they can request a -retry even if the underlying I/O structure is blocking, if a handshake -occurs during a call to BIO_read(). An application can retry the failed -call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY -on the underlying SSL structure. - -While an application may retry a failed non blocking call immediately -this is likely to be very inefficient because the call will fail -repeatedly until data can be processed or is available. 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, though -the performance may be poor if SSL BIOs are present because long delays -can occur during the initial handshake process. - -It is possible for a BIO to block indefinitely if the underlying I/O -structure cannot process or return any 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. - -=cut -- cgit v1.2.3-55-g6feb