Regenerate the manual pages after the OpenSSL update to 0.9.7e.
[dragonfly.git] / secure / lib / libcrypto / man / BIO_read.3
CommitLineData
8b0cefbb
JR
1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
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
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<>.
984263bc 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
JR
62.\"
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
984263bc 66.if n .na
8b0cefbb
JR
67.\"
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_read 3"
132.TH BIO_read 3 "2004-12-18" "0.9.7e" "OpenSSL"
984263bc 133.SH "NAME"
74dab6c2 134BIO_read, BIO_write, BIO_gets, BIO_puts \- BIO I/O functions
984263bc 135.SH "SYNOPSIS"
8b0cefbb 136.IX Header "SYNOPSIS"
984263bc
MD
137.Vb 1
138\& #include <openssl/bio.h>
139.Ve
8b0cefbb 140.PP
984263bc
MD
141.Vb 4
142\& int BIO_read(BIO *b, void *buf, int len);
143\& int BIO_gets(BIO *b,char *buf, int size);
144\& int BIO_write(BIO *b, const void *buf, int len);
145\& int BIO_puts(BIO *b,const char *buf);
146.Ve
147.SH "DESCRIPTION"
8b0cefbb
JR
148.IX Header "DESCRIPTION"
149\&\fIBIO_read()\fR attempts to read \fBlen\fR bytes from \s-1BIO\s0 \fBb\fR and places
984263bc
MD
150the data in \fBbuf\fR.
151.PP
8b0cefbb 152\&\fIBIO_gets()\fR performs the BIOs \*(L"gets\*(R" operation and places the data
984263bc 153in \fBbuf\fR. Usually this operation will attempt to read a line of data
8b0cefbb
JR
154from the \s-1BIO\s0 of maximum length \fBlen\fR. There are exceptions to this
155however, for example \fIBIO_gets()\fR on a digest \s-1BIO\s0 will calculate and
984263bc
MD
156return the digest and other BIOs may not support \fIBIO_gets()\fR at all.
157.PP
8b0cefbb 158\&\fIBIO_write()\fR attempts to write \fBlen\fR bytes from \fBbuf\fR to \s-1BIO\s0 \fBb\fR.
984263bc 159.PP
8b0cefbb 160\&\fIBIO_puts()\fR attempts to write a null terminated string \fBbuf\fR to \s-1BIO\s0 \fBb\fR
984263bc 161.SH "RETURN VALUES"
8b0cefbb 162.IX Header "RETURN VALUES"
984263bc
MD
163All these functions return either the amount of data successfully read or
164written (if the return value is positive) or that no data was successfully
165read or written if the result is 0 or \-1. If the return value is \-2 then
8b0cefbb 166the operation is not implemented in the specific \s-1BIO\s0 type.
984263bc 167.SH "NOTES"
8b0cefbb 168.IX Header "NOTES"
984263bc
MD
169A 0 or \-1 return is not necessarily an indication of an error. In
170particular when the source/sink is non-blocking or of a certain type
171it may merely be an indication that no data is currently available and that
172the application should retry the operation later.
173.PP
174One technique sometimes used with blocking sockets is to use a system call
175(such as \fIselect()\fR, \fIpoll()\fR or equivalent) to determine when data is available
176and then call \fIread()\fR to read the data. The equivalent with BIOs (that is call
8b0cefbb 177\&\fIselect()\fR on the underlying I/O structure and then call \fIBIO_read()\fR to
984263bc 178read the data) should \fBnot\fR be used because a single call to \fIBIO_read()\fR
8b0cefbb 179can cause several reads (and writes in the case of \s-1SSL\s0 BIOs) on the underlying
984263bc
MD
180I/O structure and may block as a result. Instead \fIselect()\fR (or equivalent)
181should be combined with non blocking I/O so successive reads will request
182a retry instead of blocking.
183.PP
8b0cefbb 184See \fIBIO_should_retry\fR\|(3) for details of how to
984263bc
MD
185determine the cause of a retry and other I/O issues.
186.PP
8b0cefbb
JR
187If the \fIBIO_gets()\fR function is not supported by a \s-1BIO\s0 then it possible to
188work around this by adding a buffering \s-1BIO\s0 \fIBIO_f_buffer\fR\|(3)
984263bc
MD
189to the chain.
190.SH "SEE ALSO"
74dab6c2 191.IX Header "SEE ALSO"
8b0cefbb
JR
192\&\fIBIO_should_retry\fR\|(3)
193.PP
194\&\s-1TBA\s0