1 .\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
29 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" Escape single quotes in literal strings from groff's Unicode transform.
55 .\" If the F register is turned on, we'll generate index entries on stderr for
56 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
57 .\" entries marked with X<> in POD. Of course, you'll have to process the
58 .\" output yourself in some meaningful fashion.
61 . tm Index:\\$1\t\\n%\t"\\$2"
71 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
72 .\" Fear. Run. Save yourself. No user-serviceable parts.
73 . \" fudge factors for nroff and troff
82 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
88 . \" simple accents for nroff and troff
98 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
99 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
100 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
101 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
102 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
103 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
105 . \" troff and (daisy-wheel) nroff accents
106 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
107 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
108 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
109 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
110 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
111 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
112 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
113 .ds ae a\h'-(\w'a'u*4/10)'e
114 .ds Ae A\h'-(\w'A'u*4/10)'E
115 . \" corrections for vroff
116 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
117 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
118 . \" for low resolution devices (crt and lpr)
119 .if \n(.H>23 .if \n(.V>19 \
132 .\" ========================================================================
134 .IX Title "BIO_ctrl 3"
135 .TH BIO_ctrl 3 "2009-11-06" "0.9.8l" "OpenSSL"
136 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
137 .\" way too many mistakes in technical documents.
141 BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset,
142 BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close,
143 BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending,
144 BIO_get_info_callback, BIO_set_info_callback \- BIO control operations
146 .IX Header "SYNOPSIS"
148 \& #include <openssl/bio.h>
150 \& long BIO_ctrl(BIO *bp,int cmd,long larg,void *parg);
151 \& long BIO_callback_ctrl(BIO *b, int cmd, void (*fp)(struct bio_st *, int, const char *, int, long, long));
152 \& char * BIO_ptr_ctrl(BIO *bp,int cmd,long larg);
153 \& long BIO_int_ctrl(BIO *bp,int cmd,long larg,int iarg);
155 \& int BIO_reset(BIO *b);
156 \& int BIO_seek(BIO *b, int ofs);
157 \& int BIO_tell(BIO *b);
158 \& int BIO_flush(BIO *b);
159 \& int BIO_eof(BIO *b);
160 \& int BIO_set_close(BIO *b,long flag);
161 \& int BIO_get_close(BIO *b);
162 \& int BIO_pending(BIO *b);
163 \& int BIO_wpending(BIO *b);
164 \& size_t BIO_ctrl_pending(BIO *b);
165 \& size_t BIO_ctrl_wpending(BIO *b);
167 \& int BIO_get_info_callback(BIO *b,bio_info_cb **cbp);
168 \& int BIO_set_info_callback(BIO *b,bio_info_cb *cb);
170 \& typedef void bio_info_cb(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3);
173 .IX Header "DESCRIPTION"
174 \&\fIBIO_ctrl()\fR, \fIBIO_callback_ctrl()\fR, \fIBIO_ptr_ctrl()\fR and \fIBIO_int_ctrl()\fR
175 are \s-1BIO\s0 \*(L"control\*(R" operations taking arguments of various types.
176 These functions are not normally called directly, various macros
177 are used instead. The standard macros are described below, macros
178 specific to a particular type of \s-1BIO\s0 are described in the specific
179 BIOs manual page as well as any special features of the standard
182 \&\fIBIO_reset()\fR typically resets a \s-1BIO\s0 to some initial state, in the case
183 of file related BIOs for example it rewinds the file pointer to the
186 \&\fIBIO_seek()\fR resets a file related \s-1BIO\s0's (that is file descriptor and
187 \&\s-1FILE\s0 BIOs) file position pointer to \fBofs\fR bytes from start of file.
189 \&\fIBIO_tell()\fR returns the current file position of a file related \s-1BIO\s0.
191 \&\fIBIO_flush()\fR normally writes out any internally buffered data, in some
192 cases it is used to signal \s-1EOF\s0 and that no more data will be written.
194 \&\fIBIO_eof()\fR returns 1 if the \s-1BIO\s0 has read \s-1EOF\s0, the precise meaning of
195 \&\*(L"\s-1EOF\s0\*(R" varies according to the \s-1BIO\s0 type.
197 \&\fIBIO_set_close()\fR sets the \s-1BIO\s0 \fBb\fR close flag to \fBflag\fR. \fBflag\fR can
198 take the value \s-1BIO_CLOSE\s0 or \s-1BIO_NOCLOSE\s0. Typically \s-1BIO_CLOSE\s0 is used
199 in a source/sink \s-1BIO\s0 to indicate that the underlying I/O stream should
200 be closed when the \s-1BIO\s0 is freed.
202 \&\fIBIO_get_close()\fR returns the BIOs close flag.
204 \&\fIBIO_pending()\fR, \fIBIO_ctrl_pending()\fR, \fIBIO_wpending()\fR and \fIBIO_ctrl_wpending()\fR
205 return the number of pending characters in the BIOs read and write buffers.
206 Not all BIOs support these calls. \fIBIO_ctrl_pending()\fR and \fIBIO_ctrl_wpending()\fR
207 return a size_t type and are functions, \fIBIO_pending()\fR and \fIBIO_wpending()\fR are
208 macros which call \fIBIO_ctrl()\fR.
210 .IX Header "RETURN VALUES"
211 \&\fIBIO_reset()\fR normally returns 1 for success and 0 or \-1 for failure. File
212 BIOs are an exception, they return 0 for success and \-1 for failure.
214 \&\fIBIO_seek()\fR and \fIBIO_tell()\fR both return the current file position on success
215 and \-1 for failure, except file BIOs which for \fIBIO_seek()\fR always return 0
216 for success and \-1 for failure.
218 \&\fIBIO_flush()\fR returns 1 for success and 0 or \-1 for failure.
220 \&\fIBIO_eof()\fR returns 1 if \s-1EOF\s0 has been reached 0 otherwise.
222 \&\fIBIO_set_close()\fR always returns 1.
224 \&\fIBIO_get_close()\fR returns the close flag value: \s-1BIO_CLOSE\s0 or \s-1BIO_NOCLOSE\s0.
226 \&\fIBIO_pending()\fR, \fIBIO_ctrl_pending()\fR, \fIBIO_wpending()\fR and \fIBIO_ctrl_wpending()\fR
227 return the amount of pending data.
230 \&\fIBIO_flush()\fR, because it can write data may return 0 or \-1 indicating
231 that the call should be retried later in a similar manner to \fIBIO_write()\fR.
232 The \fIBIO_should_retry()\fR call should be used and appropriate action taken
235 The return values of \fIBIO_pending()\fR and \fIBIO_wpending()\fR may not reliably
236 determine the amount of pending data in all cases. For example in the
237 case of a file \s-1BIO\s0 some data may be available in the \s-1FILE\s0 structures
238 internal buffers but it is not possible to determine this in a
239 portably way. For other types of \s-1BIO\s0 they may not be supported.
241 Filter BIOs if they do not internally handle a particular \fIBIO_ctrl()\fR
242 operation usually pass the operation to the next \s-1BIO\s0 in the chain.
243 This often means there is no need to locate the required \s-1BIO\s0 for
244 a particular operation, it can be called on a chain and it will
245 be automatically passed to the relevant \s-1BIO\s0. However this can cause
246 unexpected results: for example no current filter BIOs implement
247 \&\fIBIO_seek()\fR, but this may still succeed if the chain ends in a \s-1FILE\s0
248 or file descriptor \s-1BIO\s0.
250 Source/sink BIOs return an 0 if they do not recognize the \fIBIO_ctrl()\fR
254 Some of the return values are ambiguous and care should be taken. In
255 particular a return value of 0 can be returned if an operation is not
256 supported, if an error occurred, if \s-1EOF\s0 has not been reached and in
257 the case of \fIBIO_seek()\fR on a file \s-1BIO\s0 for a successful operation.
259 .IX Header "SEE ALSO"