*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> BIO_s_bio (3)              



NAME    [Toc]    [Back]

       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_get_write_guarantee,
       BIO_ctrl_get_write_guarantee,        BIO_get_read_request,
       BIO_ctrl_reset_read_request - BIO pair BIO

SYNOPSIS    [Toc]    [Back]

       #include <openssl/bio.h>

       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

       #define  BIO_shutdown_wr(b)  (int)BIO_ctrl(b,  BIO_C_SHUTDOWN_WR,
 0, NULL)

       #define                     BIO_set_write_buf_size(b,size)
       #define                     BIO_get_write_buf_size(b,size)

       int BIO_new_bio_pair(
               BIO **bio1,
               size_t writebuf1,
               BIO **bio2,
               size_t writebuf2 ); #define  BIO_get_write_guarantee(b)

       size_t BIO_ctrl_get_write_guarantee(
               BIO    *b   );   #define   BIO_get_read_request(b)

       size_t BIO_ctrl_get_read_request(
               BIO *b ); int BIO_ctrl_reset_read_request(
               BIO *b );

DESCRIPTION    [Toc]    [Back]

       The BIO_s_bio() function 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.

       The  BIO_reset()  function  clears  any  data in the write

       The BIO_make_bio_pair() function joins two  separate  BIOs
       into a connected pair.

       The  BIO_destroy_pair()  function destroys the association
       between two connected BIOs. Freeing up  any  half  of  the
       pair will automatically destroy the association.

       The 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.

       The   BIO_set_write_buf_size()  function  sets  the  write
       buffer size of BIO b to size. If the size is not  initialized
  a default value is used. This is currently 17K, sufficient
 for a maximum size TLS record.

       The BIO_get_write_buf_size() function returns the size  of
       the write buffer.

       The  BIO_new_bio_pair()  function  combines  the  calls to
       BIO_new(),            BIO_make_bio_pair(),             and
       BIO_set_write_buf_size()  to  create  a  connected pair of
       BIOs, bio1 and bio2, with write buffer sizes writebuf1 and
       writebuf2. If either size is zero then the default size is

       BIO_get_write_guarantee()  and  BIO_ctrl_get_write_guarantee()
  return the maximum length of data that can be 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.  BIO_get_read_request()  never
       returns   an   amount   larger   than   that  returned  by

       BIO_ctrl_reset_read_request() can also be  used  to  reset
       the value returned by BIO_get_read_request() to zero.

NOTES    [Toc]    [Back]

       Both  halves  of  a  BIO pair should be freed. 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

       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.

SEE ALSO    [Toc]    [Back]

       Functions:      SSL_set_bio(3),      ssl(3),       bio(3),
       BIO_ctrl_get_read_request(3),         BIO_new_bio_pair(3),
       BIO_should_retry(3), BIO_read(3)

[ Back ]
 Similar pages
Name OS Title
DSA_generate_key Tru64 Generate DSA key pair
BIO_new_bio_pair Tru64 Create a new BIO pair
RSA_generate_key Tru64 Generate RSA key pair
DSA_generate_key OpenBSD generate DSA key pair
BIO_new_bio_pair NetBSD create a new BIO pair
RSA_generate_key NetBSD generate RSA key pair
RSA_generate_key OpenBSD generate RSA key pair
DSA_generate_key NetBSD generate DSA key pair
socketpair IRIX create a pair of connected sockets
socketpair OpenBSD create a pair of connected sockets
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service