168651Skris=pod 268651Skris 368651Skris=head1 NAME 468651Skris 568651SkrisBIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset, 668651SkrisBIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close, 768651SkrisBIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending, 868651SkrisBIO_get_info_callback, BIO_set_info_callback - BIO control operations 968651Skris 1068651Skris=head1 SYNOPSIS 1168651Skris 1268651Skris #include <openssl/bio.h> 1368651Skris 1468651Skris long BIO_ctrl(BIO *bp,int cmd,long larg,void *parg); 1568651Skris long BIO_callback_ctrl(BIO *b, int cmd, void (*fp)(struct bio_st *, int, const char *, int, long, long)); 1668651Skris char * BIO_ptr_ctrl(BIO *bp,int cmd,long larg); 1768651Skris long BIO_int_ctrl(BIO *bp,int cmd,long larg,int iarg); 1868651Skris 1968651Skris int BIO_reset(BIO *b); 2068651Skris int BIO_seek(BIO *b, int ofs); 2168651Skris int BIO_tell(BIO *b); 2268651Skris int BIO_flush(BIO *b); 2368651Skris int BIO_eof(BIO *b); 2468651Skris int BIO_set_close(BIO *b,long flag); 2568651Skris int BIO_get_close(BIO *b); 2668651Skris int BIO_pending(BIO *b); 2768651Skris int BIO_wpending(BIO *b); 2868651Skris size_t BIO_ctrl_pending(BIO *b); 2968651Skris size_t BIO_ctrl_wpending(BIO *b); 3068651Skris 3168651Skris int BIO_get_info_callback(BIO *b,bio_info_cb **cbp); 3268651Skris int BIO_set_info_callback(BIO *b,bio_info_cb *cb); 3368651Skris 3468651Skris typedef void bio_info_cb(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3); 3568651Skris 3668651Skris=head1 DESCRIPTION 3768651Skris 3868651SkrisBIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl() and BIO_int_ctrl() 3968651Skrisare BIO "control" operations taking arguments of various types. 4068651SkrisThese functions are not normally called directly, various macros 4168651Skrisare used instead. The standard macros are described below, macros 4268651Skrisspecific to a particular type of BIO are described in the specific 4368651SkrisBIOs manual page as well as any special features of the standard 4468651Skriscalls. 4568651Skris 4668651SkrisBIO_reset() typically resets a BIO to some initial state, in the case 4768651Skrisof file related BIOs for example it rewinds the file pointer to the 4868651Skrisstart of the file. 4968651Skris 5068651SkrisBIO_seek() resets a file related BIO's (that is file descriptor and 5168651SkrisFILE BIOs) file position pointer to B<ofs> bytes from start of file. 5268651Skris 5368651SkrisBIO_tell() returns the current file position of a file related BIO. 5468651Skris 5568651SkrisBIO_flush() normally writes out any internally buffered data, in some 5668651Skriscases it is used to signal EOF and that no more data will be written. 5768651Skris 5868651SkrisBIO_eof() returns 1 if the BIO has read EOF, the precise meaning of 5968651Skris"EOF" varies according to the BIO type. 6068651Skris 6168651SkrisBIO_set_close() sets the BIO B<b> close flag to B<flag>. B<flag> can 6268651Skristake the value BIO_CLOSE or BIO_NOCLOSE. Typically BIO_CLOSE is used 6368651Skrisin a source/sink BIO to indicate that the underlying I/O stream should 6468651Skrisbe closed when the BIO is freed. 6568651Skris 6668651SkrisBIO_get_close() returns the BIOs close flag. 6768651Skris 6868651SkrisBIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() 6968651Skrisreturn the number of pending characters in the BIOs read and write buffers. 7068651SkrisNot all BIOs support these calls. BIO_ctrl_pending() and BIO_ctrl_wpending() 7168651Skrisreturn a size_t type and are functions, BIO_pending() and BIO_wpending() are 7268651Skrismacros which call BIO_ctrl(). 7368651Skris 7468651Skris=head1 RETURN VALUES 7568651Skris 7668651SkrisBIO_reset() normally returns 1 for success and 0 or -1 for failure. File 7768651SkrisBIOs are an exception, they return 0 for success and -1 for failure. 7868651Skris 7968651SkrisBIO_seek() and BIO_tell() both return the current file position on success 8068651Skrisand -1 for failure, except file BIOs which for BIO_seek() always return 0 8168651Skrisfor success and -1 for failure. 8268651Skris 8368651SkrisBIO_flush() returns 1 for success and 0 or -1 for failure. 8468651Skris 8568651SkrisBIO_eof() returns 1 if EOF has been reached 0 otherwise. 8668651Skris 8768651SkrisBIO_set_close() always returns 1. 8868651Skris 8968651SkrisBIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE. 9068651Skris 9168651SkrisBIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() 9268651Skrisreturn the amount of pending data. 9368651Skris 9468651Skris=head1 NOTES 9568651Skris 9668651SkrisBIO_flush(), because it can write data may return 0 or -1 indicating 9768651Skristhat the call should be retried later in a similar manner to BIO_write(). 9868651SkrisThe BIO_should_retry() call should be used and appropriate action taken 9968651Skrisis the call fails. 10068651Skris 10168651SkrisThe return values of BIO_pending() and BIO_wpending() may not reliably 10268651Skrisdetermine the amount of pending data in all cases. For example in the 10368651Skriscase of a file BIO some data may be available in the FILE structures 10468651Skrisinternal buffers but it is not possible to determine this in a 10568651Skrisportably way. For other types of BIO they may not be supported. 10668651Skris 10768651SkrisFilter BIOs if they do not internally handle a particular BIO_ctrl() 10868651Skrisoperation usually pass the operation to the next BIO in the chain. 10968651SkrisThis often means there is no need to locate the required BIO for 11068651Skrisa particular operation, it can be called on a chain and it will 11168651Skrisbe automatically passed to the relevant BIO. However this can cause 11268651Skrisunexpected results: for example no current filter BIOs implement 11368651SkrisBIO_seek(), but this may still succeed if the chain ends in a FILE 11468651Skrisor file descriptor BIO. 11568651Skris 11668651SkrisSource/sink BIOs return an 0 if they do not recognize the BIO_ctrl() 11768651Skrisoperation. 11868651Skris 11968651Skris=head1 BUGS 12068651Skris 12168651SkrisSome of the return values are ambiguous and care should be taken. In 12268651Skrisparticular a return value of 0 can be returned if an operation is not 12368651Skrissupported, if an error occurred, if EOF has not been reached and in 12468651Skristhe case of BIO_seek() on a file BIO for a successful operation. 12568651Skris 12668651Skris=head1 SEE ALSO 12768651Skris 12868651SkrisTBA 129