#use wml::openssl-macros area=docs page=BIO_ctrl

<title>Documents, BIO_ctrl(3)</title>

<h1>BIO_ctrl(3)</h1>

#use wml::imp::generic

{:
## What's this? [[s|(<STRONG>[^<].+?)</A>(</STRONG><DD>)|$1$2|sg]]
[[s|<P>\s+<P>|<P>|sg]]
[[s|<P>\s+</|</|sg]]
[[s|<DD>\s*<DT>|<DD>&nbsp;<DT>|sg]]
[[s|<DD>\s*</DL>|<DD>&nbsp;</DL>|sg]]
[[s|\[|&#91;|sg]]
[[s|\]|&#93;|sg]]

<!-- INDEX BEGIN -->

<UL>

	<LI><A HREF="#NAME">NAME</A>
	<LI><A HREF="#SYNOPSIS">SYNOPSIS</A>
	<LI><A HREF="#DESCRIPTION">DESCRIPTION</A>
	<LI><A HREF="#RETURN_VALUES">RETURN VALUES</A>
	<LI><A HREF="#NOTES">NOTES</A>
	<LI><A HREF="#BUGS">BUGS</A>
	<LI><A HREF="#SEE_ALSO">SEE ALSO</A>
</UL>
<!-- INDEX END -->

<HR>
<P>
<HR>
<H1><A NAME="NAME">NAME</A></H1>
<P>
BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset,
BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close,
BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending,
BIO_get_info_callback, BIO_set_info_callback - BIO control operations

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/bio.h&gt;
</PRE>
<PRE> 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);
</PRE>
<PRE> 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);
</PRE>
<PRE> int BIO_get_info_callback(BIO *b,bio_info_cb **cbp);
 int BIO_set_info_callback(BIO *b,bio_info_cb *cb);
</PRE>
<PRE> typedef void bio_info_cb(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
<CODE>BIO_ctrl(),</CODE> <CODE>BIO_callback_ctrl(),</CODE>
<CODE>BIO_ptr_ctrl()</CODE> and <CODE>BIO_int_ctrl()</CODE> are BIO
``control'' operations taking arguments of various types. These functions
are not normally 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 BIOs manual page as well as any
special features of the standard calls.

</P>
<P>
<CODE>BIO_reset()</CODE> 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.

</P>
<P>
<CODE>BIO_seek()</CODE> resets a file related BIO's (that is file
descriptor and FILE BIOs) file position pointer to <STRONG>ofs</STRONG> bytes from start of file.

</P>
<P>
<CODE>BIO_tell()</CODE> returns the current file position of a file related
BIO.

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

</P>
<P>
<CODE>BIO_eof()</CODE> returns 1 if the BIO has read EOF, the precise
meaning of ``EOF'' varies according to the BIO type.

</P>
<P>
<CODE>BIO_set_close()</CODE> sets the BIO <STRONG>b</STRONG> close flag to <STRONG>flag</STRONG>. <STRONG>flag</STRONG> 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.

</P>
<P>
<CODE>BIO_get_close()</CODE> returns the BIOs close flag.

</P>
<P>
<CODE>BIO_pending(),</CODE> <CODE>BIO_ctrl_pending(),</CODE>
<CODE>BIO_wpending()</CODE> and <CODE>BIO_ctrl_wpending()</CODE> return the
number of pending characters in the BIOs read and write buffers. Not all
BIOs support these calls. <CODE>BIO_ctrl_pending()</CODE> and
<CODE>BIO_ctrl_wpending()</CODE> return a size_t type and are functions,
<CODE>BIO_pending()</CODE> and <CODE>BIO_wpending()</CODE> are macros which
call <CODE>BIO_ctrl().</CODE>

</P>
<P>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
<CODE>BIO_reset()</CODE> 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.

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

</P>
<P>
<CODE>BIO_flush()</CODE> returns 1 for success and 0 or -1 for failure.

</P>
<P>
<CODE>BIO_eof()</CODE> returns 1 if EOF has been reached 0 otherwise.

</P>
<P>
<CODE>BIO_set_close()</CODE> always returns 1.

</P>
<P>
<CODE>BIO_get_close()</CODE> returns the close flag value: BIO_CLOSE or
BIO_NOCLOSE.

</P>
<P>
<CODE>BIO_pending(),</CODE> <CODE>BIO_ctrl_pending(),</CODE>
<CODE>BIO_wpending()</CODE> and <CODE>BIO_ctrl_wpending()</CODE> return the
amount of pending data.

</P>
<P>
<HR>
<H1><A NAME="NOTES">NOTES</A></H1>
<P>
<CODE>BIO_flush(),</CODE> because it can write data may return 0 or -1
indicating that the call should be retried later in a similar manner to
<CODE>BIO_write().</CODE> The <CODE>BIO_should_retry()</CODE> call should
be used and appropriate action taken is the call fails.

</P>
<P>
The return values of <CODE>BIO_pending()</CODE> and
<CODE>BIO_wpending()</CODE> may 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 structures internal buffers but it is not
possible to determine this in a portably way. For other types of BIO they
may not be supported.

</P>
<P>
Filter BIOs if they do not internally handle a particular
<CODE>BIO_ctrl()</CODE> 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
<CODE>BIO_seek(),</CODE> but this may still succeed if the chain ends in a
FILE or file descriptor BIO.

</P>
<P>
Source/sink BIOs return an 0 if they do not recognize the
<CODE>BIO_ctrl()</CODE> operation.

</P>
<P>
<HR>
<H1><A NAME="BUGS">BUGS</A></H1>
<P>
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 <CODE>BIO_seek()</CODE> on a file BIO for a successful operation. 

</P>
<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
<P>
TBA
</P>
:}