RSA BSAFE Micro Edition Suite

Streamlined security for mobile and embedded devices
Search  Print

State Operations

This section lists the operations used to set or determine the state of the BIO. The states include:
  • Data pending in the buffer for a write operation.
  • Data pending in the buffer for a read operation.
  • Data in the buffer should retry write.
  • Data not in the buffer should retry read.
  • Close I/O device on BIO_free().

    Functions

    int BIO_set_close (BIO *bio, long mode)
     Sets the close mode for the BIO bio. More...

    int BIO_get_close (BIO *bio)
     Returns the close flag for the BIO bio. More...

    int BIO_pending (BIO *bio)
     Indicates that additional buffered data is available internally for the application to read from the BIO bio. More...

    int BIO_wpending (BIO *bio)
     Indicates that all the data in the buffer has not yet been written. More...

    int BIO_flush (BIO *bio)
     Flushes any data stored in any output buffers of the BIO stack bio. More...

    int BIO_get_info_cb (BIO *bio, char *cbp)
     Retrieves the information callback set against the BIO bio. More...

    int BIO_set_info_cb (BIO *bio, char *cbp)
     Sets the information callback against BIO bio. More...

    void R_CDECL BIO_set_flags (BIO *bio, int f)
     Sets the flags indicating the current state of the BIO bio. More...

    int R_CDECL BIO_get_flags (BIO *bio)
     Returns the flags indicating the current state of the BIO bio. More...

    void R_CDECL BIO_set_retry_special (BIO *bio)
     Sets the retry flag and the mode of retry to BIO_FLAGS_IO_SPECIAL for the connection BIO bio. More...

    void R_CDECL BIO_set_retry_read (BIO *bio)
     Sets the retry flag and the mode of retry to BIO_FLAGS_READ for the connection BIO bio. More...

    void R_CDECL BIO_set_retry_write (BIO *bio)
     Sets the retry flag and the mode of retry to BIO_FLAGS_WRITE for the connection BIO bio. More...

    void R_CDECL BIO_clear_flags (BIO *bio, int f)
     Clears the flags used internally by the BIO bio. More...

    void R_CDECL BIO_clear_retry_flags (BIO *bio)
     Clears the flags field for BIO_FLAGS_RWS and BIO_FLAGS_SHOULD_RETRY for the BIO bio. More...

    int R_CDECL BIO_get_retry_flags (BIO *bio)
     Retrieves the settings from the retry flags field for the BIO bio. More...

    int R_CDECL BIO_should_read (BIO *bio)
     Indicates whether the last read operation should be retried for the BIO bio. More...

    int R_CDECL BIO_should_write (BIO *bio)
     Indicates whether the last write operation should be retried for the BIO bio. More...

    int R_CDECL BIO_should_io_special (BIO *bio)
     Indicates a BIO-specific retry reason caused the transitory error for the BIO bio. More...

    int R_CDECL BIO_retry_type (BIO *bio)
     Returns the setting corresponding to the BIO_FLAGS_RWS flag for the BIO bio and indicates of the type of retry required. More...

    int R_CDECL BIO_should_retry (BIO *bio)
     Indicates whether the last I/O operation (read or write) should be retried for the BIO bio. More...

    int R_CDECL BIO_get_retry_reason (BIO *bio)
     Returns the settings from the retry reason field for the BIO bio. More...

    char* R_CDECL BIO_method_name (BIO *bio)
     Returns the name field for the method structure for the BIO bio. More...

    int R_CDECL BIO_method_type (BIO *bio)
     Returns the numeric type of the method structure for the BIO bio. More...

    Function Documentation

    void R_CDECL BIO_clear_flags (  BIO *    bio,
    int    flags
    )  ;
     

    Clears the flags used internally by the BIO bio.

    Parameters:
    bio [In] A reference to the BIO.
    flags [In] The flags to clear.
    See also:
    BIO_clear_retry_flags(), BIO_get_retry_flags() and Flag Identifiers.

    void R_CDECL BIO_clear_retry_flags (  BIO *    bio )  ;
     

    Clears the flags field for BIO_FLAGS_RWS and BIO_FLAGS_SHOULD_RETRY for the BIO bio.

    Parameters:
    bio [In, Out] A reference to the BIO.
    See also:
    BIO_get_retry_flags(), BIO_clear_flags() and Flag Identifiers.
    Example:

    /* $Id: bio_clear_retry_flags.c,v 1.3 2003/06/03 01:59:46 cmueller Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved.
 *
 * This work contains proprietary information of RSA Security.
 * Distribution is limited to authorized licensees of RSA
 * Security. Any unauthorized reproduction, distribution or
 * modification of this work is strictly prohibited.
 */
int len = size;

/* Reset flags before a BIO_read() or BIO_write() operation. This enables
/* verification to determine whether to retry the read/write operation
*/
BIO_clear_retry_flags(bio);
if (BIO_read(bio, buf, size)==1)
{
    /* Verify if this is a retry or an error */
    if (BIO_should_retry(bio))
    {
        /* Should retry */
    }
    else
    {
        /* Read error - perform error processing */
    }
}

    int BIO_flush (  BIO *    bio )  ;
     

    Flushes any data stored in any output buffers of the BIO stack bio.

    Parameters:
    bio [In] A reference to the BIO stack.
    Returns:
    1 indicates the BIO stack was flushed.
    <= 0 indicates error.
    note.gif
    Not all BIOs buffer data.
    Example:

    /* $Id: bio_flush.c,v 1.2 2003/05/23 05:20:02 sparki Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved. 
 *
 * This work contains proprietary information of RSA Security. 
 * Distribution is limited to authorized licensees of RSA 
 * Security. Any unauthorized reproduction, distribution or 
 * modification of this work is strictly prohibited.
 */
int ret; 
FILE *fp; 

fp = fopen("myfile.dat","r+"); 

/* Put the file pointer in a BIO */ 
bio = BIO_new_fp(fp,BIO_CLOSE); 

/* Write data to the BIO */ 

/* Flush the data */ 
ret = BIO_flush(bio); 
if ( ret <= 0) 
{ 
    /* Error condition */ 
} 

/* Free BIO and close the file */ 
BIO_free(bio);
    Samples:
    cache_server.c, r_gnrt.c, and reqgen.c.

    int BIO_get_close (  BIO *    bio )  ;
     

    Returns the close flag for the BIO bio.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
    The close flag. One of:
  • 0 indicates BIO_NOCLOSE.
  • 1 indicates BIO_CLOSE.
    • See also:
    BIO_set_close(), BIO_new_fp() and Shutdown Identifiers.

    int R_CDECL BIO_get_flags (  BIO *    bio )  ;
     

    Returns the flags indicating the current state of the BIO bio.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
    The flags indicating the current state of the BIO.
    See Flag Identifiers for valid values.
    See also:
    BIO_set_flags(), BIO_should_io_special(), BIO_should_read() and BIO_should_write().

    int BIO_get_info_cb (  BIO *    bio,
    char *    cbp
    )  ;
     

    Retrieves the information callback set against the BIO bio.

    Parameters:
    bio [In] A reference to the BIO against which the callback is to be returned.
    cbp [Out] The callback pointer.
    Returns:
    1 indicates the callback is returned.
    <= 0 indicates error.
    See also:
    BIO_set_info_cb()

    int R_CDECL BIO_get_retry_flags (  BIO *    bio )  ;
     

    Retrieves the settings from the retry flags field for the BIO bio. The flags indicate whether a retry should be performed, and the type of retry to perform.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
    0 indicates that the retry flags are not set.
    > 0 indicates that the retry flags are set.
    note.gif
    This function performs the same operations as both BIO_retry_type() and BIO_should_retry().
    Use BIO_FLAGS_SHOULD_RETRY to determine whether to retry.
    Retry types are BIO_FLAGS_READ, BIO_FLAGS_WRITE and BIO_FLAGS_IO_SPECIAL.
    See also:
    BIO_clear_retry_flags() and Flag Identifiers.

    int R_CDECL BIO_get_retry_reason (  BIO *    bio )  ;
     

    Returns the settings from the retry reason field for the BIO bio. If an error occurs and is able to be retried, (for example a non-blocking I/O error), this function returns the reason it should be retried.

    For example, if BIO_should_retry() is set and BIO_read() is attempted and returns -1, then attempt BIO_get_retry_reason(). Wait for more data to become available and retry the read operation.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
    0 indicates the retry reason is not set.
    >0 indicates the retry reason is set.
    See Retry Reason Identifiers for valid values.
    See also:
    BIO_get_retry_flags() and BIO_get_retry_BIO().

    char* R_CDECL BIO_method_name (  BIO *    bio )  ;
     

    Returns the name field for the method structure for the BIO bio. The method name is set during BIO creation.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
    The method name. One of:
  • "buffer".
  • "file descriptor".
  • "FILE pointer".
  • "memory buffer".
  • "non-blocking I/O test filter".
  • "NULL".
  • "NULL filter".
  • "socket".
  • "socket accept".
  • "socket connect".
    • See also:
    BIO_method_type().

    int R_CDECL BIO_method_type (  BIO *    bio )  ;
     

    Returns the numeric type of the method structure for the BIO bio. The method type is set during BIO creation.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
    The method type.
    See Type Identifiers for valid values.
    See also:
    BIO_method_name().

    int BIO_pending (  BIO *    bio )  ;
     

    Indicates that additional buffered data is available internally for the application to read from the BIO bio. The remaining Bytes can be read from the internal data buffer without reading any more data from the peer. When using select system calls, BIO_pending() helps the application avoid waiting for data from the peer when it is already available in a local buffer.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
    1 indicates success.
    <=0 indicates error.

    int R_CDECL BIO_retry_type (  BIO *    bio )  ;
     

    Returns the setting corresponding to the BIO_FLAGS_RWS flag for the BIO bio and indicates of the type of retry required.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
  • >0 indicates the flag is set.
  • 0 indicates the flag is not set.
  • -1 indicates error.
    • note.gif
    The flag setting can be one of:
  • BIO_FLAGS_READ.
  • BIO_FLAGS_WRITE.
  • BIO_FLAGS_IO_SPECIAL.
    • See also:
    BIO_should_retry(),BIO_get_retry_flags() and Flag Identifiers.

    int BIO_set_close (  BIO *    bio,
    long    mode
    )  ;
     

    Sets the close mode for the BIO bio. When a BIO is freed, the underlying file descriptor or pointer is closed/freed depending on the specified flag. In particular, if there is a file pointer BIO implementing stdout, do not close stdout when the BIO is freed.

    Parameters:
    bio [In, Out] A reference to the BIO.
    mode [In] The close flag.
    See Shutdown Identifiers for valid values.
    Returns:
    The close flag. One of:
  • 0 indicates BIO_NOCLOSE.
  • 1 indicates BIO_CLOSE.
    • See also:
    BIO_get_close() and Shutdown Identifiers.

    void R_CDECL BIO_set_flags (  BIO *    bio,
    int    flags
    )  ;
     

    Sets the flags indicating the current state of the BIO bio.

    Parameters:
    bio [In] The BIO reference.
    flags [In] The flags to set.
    See Flag Identifiers for valid values.
    See also:
    BIO_get_flags(), BIO_should_io_special(), BIO_should_read() and BIO_should_write().
    Samples:
    bio_client.c, bio_server.c, cache_server.c, cm_env.c, cm_env_sm.c, cm_env_strm.c, cm_env_strm_membio.c, cm_open.c, cm_sign.c, cm_sign_dgst.c, cm_sign_sm.c, cm_sign_strm.c, evpkey2rpkey.c, nbio_client.c, nbio_server.c, p7ssl_client.c, p7ssl_server.c, rcert2sslcert.c, reslist_set.c, s_crl_check.c, s_crl_verify.c, sock_client.c, sock_server.c, ssl_client.c, ssl_server.c, sslcert2rcert.c, and thread.c.

    int BIO_set_info_cb (  BIO *    bio,
    char *    cbp
    )  ;
     

    Sets the information callback against BIO bio.

    Parameters:
    bio [In] A reference to the BIO against which the callback is to be set.
    cbp [Out] The callback to be set against bio.
    Returns:
    1 indicates the callback is set.
    <= 0 indicates errors.
    See also:
    BIO_get_info_cb()

    void R_CDECL BIO_set_retry_read (  BIO *    bio )  ;
     

    Sets the retry flag and the mode of retry to BIO_FLAGS_READ for the connection BIO bio.

    Parameters:
    bio [In, Out] A reference to the BIO.
    See also:
    BIO_clear_retry_flags(), BIO_should_retry(), BIO_retry_type(), BIO_get_retry_flags() and Flag Identifiers.

    void R_CDECL BIO_set_retry_special (  BIO *    bio )  ;
     

    Sets the retry flag and the mode of retry to BIO_FLAGS_IO_SPECIAL for the connection BIO bio.

    Parameters:
    bio [In, Out] A reference to the BIO.
    See also:
    BIO_clear_retry_flags(), BIO_should_retry(), BIO_retry_type(), BIO_get_retry_flags() and Flag Identifiers.

    void R_CDECL BIO_set_retry_write (  BIO *    bio )  ;
     

    Sets the retry flag and the mode of retry to BIO_FLAGS_WRITE for the connection BIO bio.

    Parameters:
    bio [In, Out] A reference to the BIO.
    See also:
    BIO_clear_retry_flags(), BIO_should_retry(), BIO_retry_type(), BIO_get_retry_flags() and Flag Identifiers.

    int R_CDECL BIO_should_io_special (  BIO *    bio )  ;
     

    Indicates a BIO-specific retry reason caused the transitory error for the BIO bio. The most common transitory error occurs when using a non-blocking I/O connection.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
    The current value of the io_special.
    The BIO flag. See Flag Identifiers for valid values.
    <= 0 indicates error.
    See also:
    BIO_get_retry_reason() and Flag Identifiers.

    int R_CDECL BIO_should_read (  BIO *    bio )  ;
     

    Indicates whether the last read operation should be retried for the BIO bio. This is used with a non-blocking I/O to distinguish between a temporary failure to complete an operation and an error.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
    1 indicates the read operation should be retried.
    <= 0 indicates the read operation should not be retried.
    See also:
    Flag Identifiers.

    int R_CDECL BIO_should_retry (  BIO *    bio )  ;
     

    Indicates whether the last I/O operation (read or write) should be retried for the BIO bio. This is used with non-blocking I/O to distinguish between a temporary failure to complete an operation and an error.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
    0 indicates the I/O operation should not be retried.
    Non-zero indicates to retry the I/O operation.
    See also:
    Flag Identifiers.
    Samples:
    cm_dgst.c, cm_env_strm.c, cm_env_strm_membio.c, cm_open_strm.c, cm_open_strm_cb.c, cm_open_strm_membio.c, cm_sign_dgst.c, cm_sign_strm.c, cm_strm.c, cm_vfy_strm_cb.c, nbio_client.c, and nbio_server.c.

    int R_CDECL BIO_should_write (  BIO *    bio )  ;
     

    Indicates whether the last write operation should be retried for the BIO bio. This is used with non-blocking I/O to distinguish between a temporary failure to complete an operation and an error.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
    1 indicates the write operation should be retried.
    <= 0 indicates the write operation should not be retried.
    See also:
    Flag Identifiers.

    int BIO_wpending (  BIO *    bio )  ;
     

    Indicates that all the data in the buffer has not yet been written. An application can keep flushing the data until this function indicates otherwise.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
    1 indicates success.
    <=0 indicates error.

    Copyright (c) 1999-2005 RSA Security Inc. All rights reserved. 072-001001-2100-001-000 - 2.1