Upgrade to OpenSSL 0.9.8h.
[dragonfly.git] / secure / lib / libcrypto / man / BIO_s_bio.3
CommitLineData
aac4ff6f 1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
8b0cefbb
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
984263bc
MD
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
8b0cefbb 13.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
14.if t .sp .5v
15.if n .sp
16..
8b0cefbb 17.de Vb \" Begin verbatim text
984263bc
MD
18.ft CW
19.nf
20.ne \\$1
21..
8b0cefbb 22.de Ve \" End verbatim text
984263bc 23.ft R
984263bc
MD
24.fi
25..
8b0cefbb
JR
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
aac4ff6f
PA
28.\" double quote, and \*(R" will give a right double quote. | will give a
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31.\" expand to `' in nroff, nothing in troff, for use with C<>.
32.tr \(*W-|\(bv\*(Tr
8b0cefbb 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 34.ie n \{\
8b0cefbb
JR
35. ds -- \(*W-
36. ds PI pi
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
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
984263bc
MD
43'br\}
44.el\{\
8b0cefbb
JR
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
984263bc 49'br\}
8b0cefbb
JR
50.\"
51.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion.
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 58..
8b0cefbb
JR
59. nr % 0
60. rr F
984263bc 61.\}
8b0cefbb 62.\"
aac4ff6f
PA
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
66.if n .na
67.\"
8b0cefbb
JR
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts.
70. \" fudge factors for nroff and troff
984263bc 71.if n \{\
8b0cefbb
JR
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
984263bc
MD
77.\}
78.if t \{\
8b0cefbb
JR
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
984263bc 84.\}
8b0cefbb 85. \" simple accents for nroff and troff
984263bc 86.if n \{\
8b0cefbb
JR
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
984263bc
MD
93.\}
94.if t \{\
8b0cefbb
JR
95. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 101.\}
8b0cefbb 102. \" troff and (daisy-wheel) nroff accents
984263bc
MD
103.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110.ds ae a\h'-(\w'a'u*4/10)'e
111.ds Ae A\h'-(\w'A'u*4/10)'E
8b0cefbb 112. \" corrections for vroff
984263bc
MD
113.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
8b0cefbb 115. \" for low resolution devices (crt and lpr)
984263bc
MD
116.if \n(.H>23 .if \n(.V>19 \
117\{\
8b0cefbb
JR
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
984263bc
MD
127.\}
128.rm #[ #] #H #V #F C
8b0cefbb
JR
129.\" ========================================================================
130.\"
131.IX Title "BIO_s_bio 3"
aac4ff6f 132.TH BIO_s_bio 3 "2008-09-06" "0.9.8h" "OpenSSL"
984263bc
MD
133.SH "NAME"
134BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr,
135BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair,
136BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request,
74dab6c2 137BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request \- BIO pair BIO
984263bc 138.SH "SYNOPSIS"
8b0cefbb 139.IX Header "SYNOPSIS"
984263bc
MD
140.Vb 1
141\& #include <openssl/bio.h>
aac4ff6f
PA
142.Ve
143.PP
144.Vb 1
984263bc 145\& BIO_METHOD *BIO_s_bio(void);
aac4ff6f
PA
146.Ve
147.PP
148.Vb 2
984263bc
MD
149\& #define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2)
150\& #define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL)
aac4ff6f
PA
151.Ve
152.PP
153.Vb 1
984263bc 154\& #define BIO_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL)
aac4ff6f
PA
155.Ve
156.PP
157.Vb 2
984263bc
MD
158\& #define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,BIO_C_SET_WRITE_BUF_SIZE,size,NULL)
159\& #define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL)
aac4ff6f
PA
160.Ve
161.PP
162.Vb 1
984263bc 163\& int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);
aac4ff6f
PA
164.Ve
165.PP
166.Vb 2
984263bc
MD
167\& #define BIO_get_write_guarantee(b) (int)BIO_ctrl(b,BIO_C_GET_WRITE_GUARANTEE,0,NULL)
168\& size_t BIO_ctrl_get_write_guarantee(BIO *b);
aac4ff6f
PA
169.Ve
170.PP
171.Vb 2
984263bc
MD
172\& #define BIO_get_read_request(b) (int)BIO_ctrl(b,BIO_C_GET_READ_REQUEST,0,NULL)
173\& size_t BIO_ctrl_get_read_request(BIO *b);
aac4ff6f
PA
174.Ve
175.PP
176.Vb 1
984263bc
MD
177\& int BIO_ctrl_reset_read_request(BIO *b);
178.Ve
179.SH "DESCRIPTION"
8b0cefbb
JR
180.IX Header "DESCRIPTION"
181\&\fIBIO_s_bio()\fR returns the method for a \s-1BIO\s0 pair. A \s-1BIO\s0 pair is a pair of source/sink
984263bc
MD
182BIOs where data written to either half of the pair is buffered and can be read from
183the other half. Both halves must usually by handled by the same application thread
184since no locking is done on the internal data structures.
185.PP
8b0cefbb
JR
186Since \s-1BIO\s0 chains typically end in a source/sink \s-1BIO\s0 it is possible to make this
187one half of a \s-1BIO\s0 pair and have all the data processed by the chain under application
984263bc
MD
188control.
189.PP
8b0cefbb 190One typical use of \s-1BIO\s0 pairs is to place \s-1TLS/SSL\s0 I/O under application control, this
984263bc 191can be used when the application wishes to use a non standard transport for
8b0cefbb 192\&\s-1TLS/SSL\s0 or the normal socket routines are inappropriate.
984263bc
MD
193.PP
194Calls to \fIBIO_read()\fR will read data from the buffer or request a retry if no
195data is available.
196.PP
197Calls to \fIBIO_write()\fR will place data in the buffer or request a retry if the
198buffer is full.
199.PP
200The standard calls \fIBIO_ctrl_pending()\fR and \fIBIO_ctrl_wpending()\fR can be used to
201determine the amount of pending data in the read or write buffer.
202.PP
8b0cefbb 203\&\fIBIO_reset()\fR clears any data in the write buffer.
984263bc 204.PP
8b0cefbb 205\&\fIBIO_make_bio_pair()\fR joins two separate BIOs into a connected pair.
984263bc 206.PP
8b0cefbb 207\&\fIBIO_destroy_pair()\fR destroys the association between two connected BIOs. Freeing
984263bc
MD
208up any half of the pair will automatically destroy the association.
209.PP
8b0cefbb
JR
210\&\fIBIO_shutdown_wr()\fR is used to close down a \s-1BIO\s0 \fBb\fR. After this call no further
211writes on \s-1BIO\s0 \fBb\fR are allowed (they will return an error). Reads on the other
212half of the pair will return any pending data or \s-1EOF\s0 when all pending data has
aac4ff6f 213been read.
984263bc 214.PP
8b0cefbb 215\&\fIBIO_set_write_buf_size()\fR sets the write buffer size of \s-1BIO\s0 \fBb\fR to \fBsize\fR.
984263bc 216If the size is not initialized a default value is used. This is currently
8b0cefbb 21717K, sufficient for a maximum size \s-1TLS\s0 record.
984263bc 218.PP
8b0cefbb 219\&\fIBIO_get_write_buf_size()\fR returns the size of the write buffer.
984263bc 220.PP
8b0cefbb
JR
221\&\fIBIO_new_bio_pair()\fR combines the calls to \fIBIO_new()\fR, \fIBIO_make_bio_pair()\fR and
222\&\fIBIO_set_write_buf_size()\fR to create a connected pair of BIOs \fBbio1\fR, \fBbio2\fR
984263bc
MD
223with write buffer sizes \fBwritebuf1\fR and \fBwritebuf2\fR. If either size is
224zero then the default size is used. \fIBIO_new_bio_pair()\fR does not check whether
8b0cefbb
JR
225\&\fBbio1\fR or \fBbio2\fR do point to some other \s-1BIO\s0, the values are overwritten,
226\&\fIBIO_free()\fR is not called.
984263bc 227.PP
8b0cefbb
JR
228\&\fIBIO_get_write_guarantee()\fR and \fIBIO_ctrl_get_write_guarantee()\fR return the maximum
229length of data that can be currently written to the \s-1BIO\s0. Writes larger than this
984263bc
MD
230value will return a value from \fIBIO_write()\fR less than the amount requested or if the
231buffer is full request a retry. \fIBIO_ctrl_get_write_guarantee()\fR is a function
232whereas \fIBIO_get_write_guarantee()\fR is a macro.
233.PP
8b0cefbb 234\&\fIBIO_get_read_request()\fR and \fIBIO_ctrl_get_read_request()\fR return the
984263bc 235amount of data requested, or the buffer size if it is less, if the
8b0cefbb 236last read attempt at the other half of the \s-1BIO\s0 pair failed due to an
984263bc 237empty buffer. This can be used to determine how much data should be
8b0cefbb
JR
238written to the \s-1BIO\s0 so the next read will succeed: this is most useful
239in \s-1TLS/SSL\s0 applications where the amount of data read is usually
984263bc
MD
240meaningful rather than just a buffer size. After a successful read
241this call will return zero. It also will return zero once new data
242has been written satisfying the read request or part of it.
243Note that \fIBIO_get_read_request()\fR never returns an amount larger
244than that returned by \fIBIO_get_write_guarantee()\fR.
245.PP
8b0cefbb
JR
246\&\fIBIO_ctrl_reset_read_request()\fR can also be used to reset the value returned by
247\&\fIBIO_get_read_request()\fR to zero.
984263bc 248.SH "NOTES"
8b0cefbb
JR
249.IX Header "NOTES"
250Both halves of a \s-1BIO\s0 pair should be freed. That is even if one half is implicit
984263bc
MD
251freed due to a \fIBIO_free_all()\fR or \fISSL_free()\fR call the other half needs to be freed.
252.PP
8b0cefbb 253When used in bidirectional applications (such as \s-1TLS/SSL\s0) care should be taken to
984263bc
MD
254flush any data in the write buffer. This can be done by calling \fIBIO_pending()\fR
255on the other half of the pair and, if any data is pending, reading it and sending
256it to the underlying transport. This must be done before any normal processing
257(such as calling \fIselect()\fR ) due to a request and \fIBIO_should_read()\fR being true.
258.PP
259To see why this is important consider a case where a request is sent using
8b0cefbb
JR
260\&\fIBIO_write()\fR and a response read with \fIBIO_read()\fR, this can occur during an
261\&\s-1TLS/SSL\s0 handshake for example. \fIBIO_write()\fR will succeed and place data in the write
984263bc
MD
262buffer. \fIBIO_read()\fR will initially fail and \fIBIO_should_read()\fR will be true. If
263the application then waits for data to be available on the underlying transport
264before flushing the write buffer it will never succeed because the request was
265never sent!
266.SH "RETURN VALUES"
8b0cefbb
JR
267.IX Header "RETURN VALUES"
268\&\fIBIO_new_bio_pair()\fR returns 1 on success, with the new BIOs available in
269\&\fBbio1\fR and \fBbio2\fR, or 0 on failure, with \s-1NULL\s0 pointers stored into the
984263bc
MD
270locations for \fBbio1\fR and \fBbio2\fR. Check the error stack for more information.
271.PP
8b0cefbb 272[\s-1XXXXX:\s0 More return values need to be added here]
984263bc 273.SH "EXAMPLE"
8b0cefbb
JR
274.IX Header "EXAMPLE"
275The \s-1BIO\s0 pair can be used to have full control over the network access of an
984263bc 276application. The application can call \fIselect()\fR on the socket as required
aac4ff6f 277without having to go through the SSL\-interface.
984263bc
MD
278.PP
279.Vb 6
280\& BIO *internal_bio, *network_bio;
281\& ...
282\& BIO_new_bio_pair(internal_bio, 0, network_bio, 0);
283\& SSL_set_bio(ssl, internal_bio, internal_bio);
284\& SSL_operations();
285\& ...
aac4ff6f
PA
286.Ve
287.PP
288.Vb 9
289\& application | TLS-engine
984263bc 290\& | |
aac4ff6f 291\& +----------> SSL_operations()
984263bc
MD
292\& | /\e ||
293\& | || \e/
aac4ff6f
PA
294\& | BIO-pair (internal_bio)
295\& +----------< BIO-pair (network_bio)
984263bc
MD
296\& | |
297\& socket |
aac4ff6f
PA
298.Ve
299.PP
300.Vb 4
984263bc
MD
301\& ...
302\& SSL_free(ssl); /* implicitly frees internal_bio */
303\& BIO_free(network_bio);
304\& ...
305.Ve
8b0cefbb
JR
306.PP
307As the \s-1BIO\s0 pair will only buffer the data and never directly access the
984263bc
MD
308connection, it behaves non-blocking and will return as soon as the write
309buffer is full or the read buffer is drained. Then the application has to
310flush the write buffer and/or fill the read buffer.
311.PP
8b0cefbb 312Use the \fIBIO_ctrl_pending()\fR, to find out whether data is buffered in the \s-1BIO\s0
984263bc
MD
313and must be transfered to the network. Use \fIBIO_ctrl_get_read_request()\fR to
314find out, how many bytes must be written into the buffer before the
8b0cefbb 315\&\fISSL_operation()\fR can successfully be continued.
984263bc 316.SH "WARNING"
8b0cefbb
JR
317.IX Header "WARNING"
318As the data is buffered, \fISSL_operation()\fR may return with a \s-1ERROR_SSL_WANT_READ\s0
984263bc
MD
319condition, but there is still data in the write buffer. An application must
320not rely on the error value of \fISSL_operation()\fR but must assure that the
321write buffer is always flushed first. Otherwise a deadlock may occur as
322the peer might be waiting for the data before being able to continue.
323.SH "SEE ALSO"
74dab6c2 324.IX Header "SEE ALSO"
8b0cefbb
JR
325\&\fISSL_set_bio\fR\|(3), \fIssl\fR\|(3), \fIbio\fR\|(3),
326\&\fIBIO_should_retry\fR\|(3), \fIBIO_read\fR\|(3)