Update build for OpenSSL-0.9.8j upgrade.
[dragonfly.git] / secure / lib / libcrypto / man / BIO_read.3
CommitLineData
e257b235 1.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
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
e257b235
PA
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<>.
32.tr \(*W-
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 50.\"
e257b235
PA
51.\" Escape single quotes in literal strings from groff's Unicode transform.
52.ie \n(.g .ds Aq \(aq
53.el .ds Aq '
54.\"
8b0cefbb
JR
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.
e257b235 59.ie \nF \{\
8b0cefbb
JR
60. de IX
61. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 62..
8b0cefbb
JR
63. nr % 0
64. rr F
984263bc 65.\}
e257b235
PA
66.el \{\
67. de IX
68..
69.\}
aac4ff6f 70.\"
8b0cefbb
JR
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
984263bc 74.if n \{\
8b0cefbb
JR
75. ds #H 0
76. ds #V .8m
77. ds #F .3m
78. ds #[ \f1
79. ds #] \fP
984263bc
MD
80.\}
81.if t \{\
8b0cefbb
JR
82. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
83. ds #V .6m
84. ds #F 0
85. ds #[ \&
86. ds #] \&
984263bc 87.\}
8b0cefbb 88. \" simple accents for nroff and troff
984263bc 89.if n \{\
8b0cefbb
JR
90. ds ' \&
91. ds ` \&
92. ds ^ \&
93. ds , \&
94. ds ~ ~
95. ds /
984263bc
MD
96.\}
97.if t \{\
8b0cefbb
JR
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'
984263bc 104.\}
8b0cefbb 105. \" troff and (daisy-wheel) nroff accents
984263bc
MD
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
8b0cefbb 115. \" corrections for vroff
984263bc
MD
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'
8b0cefbb 118. \" for low resolution devices (crt and lpr)
984263bc
MD
119.if \n(.H>23 .if \n(.V>19 \
120\{\
8b0cefbb
JR
121. ds : e
122. ds 8 ss
123. ds o a
124. ds d- d\h'-1'\(ga
125. ds D- D\h'-1'\(hy
126. ds th \o'bp'
127. ds Th \o'LP'
128. ds ae ae
129. ds Ae AE
984263bc
MD
130.\}
131.rm #[ #] #H #V #F C
8b0cefbb
JR
132.\" ========================================================================
133.\"
134.IX Title "BIO_read 3"
e257b235
PA
135.TH BIO_read 3 "2009-01-11" "0.9.8j" "OpenSSL"
136.\" For nroff, turn off justification. Always turn off hyphenation; it makes
137.\" way too many mistakes in technical documents.
138.if n .ad l
139.nh
984263bc 140.SH "NAME"
74dab6c2 141BIO_read, BIO_write, BIO_gets, BIO_puts \- BIO I/O functions
984263bc 142.SH "SYNOPSIS"
8b0cefbb 143.IX Header "SYNOPSIS"
984263bc
MD
144.Vb 1
145\& #include <openssl/bio.h>
e257b235 146\&
984263bc
MD
147\& int BIO_read(BIO *b, void *buf, int len);
148\& int BIO_gets(BIO *b,char *buf, int size);
149\& int BIO_write(BIO *b, const void *buf, int len);
150\& int BIO_puts(BIO *b,const char *buf);
151.Ve
152.SH "DESCRIPTION"
8b0cefbb
JR
153.IX Header "DESCRIPTION"
154\&\fIBIO_read()\fR attempts to read \fBlen\fR bytes from \s-1BIO\s0 \fBb\fR and places
984263bc
MD
155the data in \fBbuf\fR.
156.PP
8b0cefbb 157\&\fIBIO_gets()\fR performs the BIOs \*(L"gets\*(R" operation and places the data
984263bc 158in \fBbuf\fR. Usually this operation will attempt to read a line of data
8b0cefbb
JR
159from the \s-1BIO\s0 of maximum length \fBlen\fR. There are exceptions to this
160however, for example \fIBIO_gets()\fR on a digest \s-1BIO\s0 will calculate and
984263bc
MD
161return the digest and other BIOs may not support \fIBIO_gets()\fR at all.
162.PP
8b0cefbb 163\&\fIBIO_write()\fR attempts to write \fBlen\fR bytes from \fBbuf\fR to \s-1BIO\s0 \fBb\fR.
984263bc 164.PP
8b0cefbb 165\&\fIBIO_puts()\fR attempts to write a null terminated string \fBbuf\fR to \s-1BIO\s0 \fBb\fR
984263bc 166.SH "RETURN VALUES"
8b0cefbb 167.IX Header "RETURN VALUES"
984263bc
MD
168All these functions return either the amount of data successfully read or
169written (if the return value is positive) or that no data was successfully
170read or written if the result is 0 or \-1. If the return value is \-2 then
8b0cefbb 171the operation is not implemented in the specific \s-1BIO\s0 type.
984263bc 172.SH "NOTES"
8b0cefbb 173.IX Header "NOTES"
984263bc
MD
174A 0 or \-1 return is not necessarily an indication of an error. In
175particular when the source/sink is non-blocking or of a certain type
176it may merely be an indication that no data is currently available and that
177the application should retry the operation later.
178.PP
179One technique sometimes used with blocking sockets is to use a system call
180(such as \fIselect()\fR, \fIpoll()\fR or equivalent) to determine when data is available
181and then call \fIread()\fR to read the data. The equivalent with BIOs (that is call
8b0cefbb 182\&\fIselect()\fR on the underlying I/O structure and then call \fIBIO_read()\fR to
984263bc 183read the data) should \fBnot\fR be used because a single call to \fIBIO_read()\fR
8b0cefbb 184can cause several reads (and writes in the case of \s-1SSL\s0 BIOs) on the underlying
984263bc
MD
185I/O structure and may block as a result. Instead \fIselect()\fR (or equivalent)
186should be combined with non blocking I/O so successive reads will request
187a retry instead of blocking.
188.PP
8b0cefbb 189See \fIBIO_should_retry\fR\|(3) for details of how to
984263bc
MD
190determine the cause of a retry and other I/O issues.
191.PP
8b0cefbb
JR
192If the \fIBIO_gets()\fR function is not supported by a \s-1BIO\s0 then it possible to
193work around this by adding a buffering \s-1BIO\s0 \fIBIO_f_buffer\fR\|(3)
984263bc
MD
194to the chain.
195.SH "SEE ALSO"
74dab6c2 196.IX Header "SEE ALSO"
8b0cefbb
JR
197\&\fIBIO_should_retry\fR\|(3)
198.PP
199\&\s-1TBA\s0