Index for Section 3

Alphabetical listing for B

Bottom of page

BIO_ctrl(3)
NAME
  BIO_ctrl, BIO_callback_ctrl, BIO_ctrl_wpending, BIO_wpending, BIO_eof,
  BIO_flush, BIO_get_close, BIO_get_info_callback, BIO_set_info_callback,
  BIO_int_ctrl, BIO_pending, BIO_ptr_ctrl, BIO_reset, BIO_seek,
  BIO_set_close, BIO_tell - BIO control operations

SYNOPSIS
  #include <openssl/bio.h>

  long BIO_ctrl(
	  BIO *bp,
	  int cmd,
	  long larg,
	  void *parg );

  long BIO_callback_ctrl(
	  BIO *b,
	  int cmd,
	  void (*fp)(struct bio_st *,
	  int,
	  const char *,
	  int,
	  long,
	  long) );

  char *  BIO_ptr_ctrl(
	  BIO *bp,
	  int cmd,
	  long larg );

  long BIO_int_ctrl(
	  BIO *bp,
	  int cmd,
	  long larg,
	  int iarg );

  int BIO_reset(
	  BIO *b );

  int BIO_seek(
	  BIO *b,
	  int ofs );

  int BIO_tell(
	  BIO *b );

  int BIO_flush(
	  BIO *b );

  int BIO_eof(
	  BIO *b );

  int BIO_set_close(
	  BIO *b,
	  long flag );

  int BIO_get_close(
	  BIO *b );

  int BIO_pending(
	  BIO *b );

  int BIO_wpending(
	  BIO *b );

  size_t BIO_ctrl_pending(
	  BIO *b );

  size_t BIO_ctrl_wpending(
	  BIO *b );

  int BIO_get_info_callback(
	  BIO *b,
	  bio_info_cb **cbp );

  int BIO_set_info_callback(
	  BIO *b,
	  bio_info_cb *cb );

  typedef void bio_info_cb(
	  BIO *b,
	  int oper,
	  const char *ptr,
	  int arg1,
	  long arg2,
	  long arg3 );

DESCRIPTION
  The BIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl(), and BIO_int_ctrl()
  functions are BIO control operations taking arguments of various types.
  These functions are not usually called directly; various macros are used
  instead. The standard macros are described below. Macros specific to a
  particular type of BIO are described in the specific BIO's reference page,
  as well as any special features of the standard calls.

  The BIO_reset()function typically resets a BIO to some initial state. In
  the case of file related BIOs, for example, it rewinds the file pointer to
  the start of the file.

  The BIO_seek() function resets a file related BIO's (its file descriptor
  and FILE BIOs) file position pointer to ofs bytes from start of file.

  The BIO_tell() function returns the current file position of a file related
  BIO.

  The BIO_flush() function normally writes out any internally buffered data,
  in some cases it is used to signal EOF and that no more data will be
  written.

  The BIO_eof() function returns 1 if the BIO has read EOF, the precise
  meaning of EOF varies according to the BIO type.

  The BIO_set_close() function sets the BIO b close flag to flag.  flag can
  take the value BIO_CLOSE or BIO_NOCLOSE.  Typically BIO_CLOSE is used in a
  source/sink BIO to indicate that the underlying I/O stream should be closed
  when the BIO is freed.

  The BIO_get_close() function returns the BIO's close flag.

  The BIO_pending(), BIO_ctrl_pending(), BIO_wpending(), and
  BIO_ctrl_wpending() functions return the number of pending characters in
  the BIO's read and write buffers.  Not all BIOs support these calls. The
  BIO_ctrl_pending() and BIO_ctrl_wpending() functions return a size_t type
  and are functions.  BIO_pending() and BIO_wpending() are macros which call
  BIO_ctrl().

NOTES
  The BIO_flush() function, because it can write data, might return 0 or -1
  indicating that the call should be retried later in a similar manner to
  BIO_write().	The BIO_should_retry() function should be used and
  appropriate action taken if the call fails.

  The return values of the BIO_pending() and BIO_wpending() functions might
  not reliably determine the amount of pending data in all cases. For
  example, in the case of a file BIO some data may be available in the FILE
  structure's internal buffers but it is not possible to determine this in a
  portably way. For other types of BIO they might not be supported.

  Filter BIOs, if they do not internally handle a particular BIO_ctrl()
  operation, usually pass the operation to the next BIO in the chain. This
  often means there is no need to locate the required BIO for a particular
  operation. It can be called on a chain and it will be automatically passed
  to the relevant BIO. However, this can cause unexpected results. For
  example, no current filter BIOs implement BIO_seek(), but this might still
  succeed if the chain ends in a FILE or file descriptor BIO.

  Source/sink BIOs return a 0 if they do not recognize the BIO_ctrl()
  operation.

RESTRICTIONS
  Some of the return values are ambiguous and care should be taken. In
  particular a return value of 0 can be returned if an operation is not
  supported, if an error occurred, if EOF has not been reached, and - in the
  case of BIO_seek() - on a file BIO for a successful operation.

RETURN VALUES
  BIO_reset() normally returns 1 for success and 0 or -1 for failure. File
  BIOs are an exception, they return 0 for success and -1 for failure.

  BIO_seek() and BIO_tell() both return the current file position on success
  and -1 for failure, except file BIOs which for BIO_seek() always return 0
  for success and -1 for failure.

  BIO_flush() returns 1 for success and 0 or -1 for failure.

  BIO_eof() returns 1 if EOF has been reached 0 otherwise.

  BIO_set_close() always returns 1.

  BIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE.

  The BIO_pending(), BIO_ctrl_pending(), BIO_wpending(), and
  BIO_ctrl_wpending() functions return the amount of pending data.

SEE ALSO
  TBA

Index for Section 3

Alphabetical listing for B

Top of page