Update per latest manual pages after running 'man-update'.
[dragonfly.git] / secure / lib / libssl / man / SSL_read.3
CommitLineData
a7d27d5a
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
a7d27d5a 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
a7d27d5a 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
a7d27d5a 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
a7d27d5a 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
a7d27d5a
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
a7d27d5a
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
a7d27d5a
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
a7d27d5a
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
a7d27d5a
JR
93.nr % 0
94.rr F
984263bc 95.\}
a7d27d5a
JR
96.TH SSL_read 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
a7d27d5a
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
a7d27d5a 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
a7d27d5a
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
a7d27d5a
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
a7d27d5a 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
a7d27d5a
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
a7d27d5a
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
a7d27d5a 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
a7d27d5a
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
a7d27d5a
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
a7d27d5a 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
a7d27d5a
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc 190.SH "NAME"
a7d27d5a 191SSL_read \- read bytes from a TLS/SSL connection.
984263bc 192.SH "SYNOPSIS"
a7d27d5a 193.PP
984263bc
MD
194.Vb 1
195\& #include <openssl/ssl.h>
196.Ve
197.Vb 1
198\& int SSL_read(SSL *ssl, void *buf, int num);
199.Ve
200.SH "DESCRIPTION"
a7d27d5a 201\fISSL_read()\fR tries to read \fBnum\fR bytes from the specified \fBssl\fR into the
984263bc
MD
202buffer \fBbuf\fR.
203.SH "NOTES"
a7d27d5a 204If necessary, \fISSL_read()\fR will negotiate a TLS/SSL session, if
984263bc
MD
205not already explicitly performed by SSL_connect(3) or
206SSL_accept(3). If the
207peer requests a re-negotiation, it will be performed transparently during
208the \fISSL_read()\fR operation. The behaviour of \fISSL_read()\fR depends on the
a7d27d5a 209underlying BIO.
984263bc
MD
210.PP
211For the transparent negotiation to succeed, the \fBssl\fR must have been
212initialized to client or server mode. This is being done by calling
213SSL_set_connect_state(3) or \fISSL_set_accept_state()\fR
214before the first call to an \fISSL_read()\fR or SSL_write(3)
215function.
216.PP
a7d27d5a 217\fISSL_read()\fR works based on the SSL/TLS records. The data are received in
984263bc
MD
218records (with a maximum record size of 16kB for SSLv3/TLSv1). Only when a
219record has been completely received, it can be processed (decryption and
220check of integrity). Therefore data that was not retrieved at the last
a7d27d5a 221call of \fISSL_read()\fR can still be buffered inside the SSL layer and will be
984263bc
MD
222retrieved on the next call to \fISSL_read()\fR. If \fBnum\fR is higher than the
223number of bytes buffered, \fISSL_read()\fR will return with the bytes buffered.
224If no more bytes are in the buffer, \fISSL_read()\fR will trigger the processing
225of the next record. Only when the record has been received and processed
226completely, \fISSL_read()\fR will return reporting success. At most the contents
a7d27d5a
JR
227of the record will be returned. As the size of an SSL/TLS record may exceed
228the maximum packet size of the underlying transport (e.g. TCP), it may
984263bc
MD
229be necessary to read several packets from the transport layer before the
230record is complete and \fISSL_read()\fR can succeed.
231.PP
a7d27d5a 232If the underlying BIO is \fBblocking\fR, \fISSL_read()\fR will only return, once the
984263bc 233read operation has been finished or an error occurred, except when a
a7d27d5a
JR
234renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur.
235This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the
984263bc
MD
236SSL_CTX_set_mode(3) call.
237.PP
a7d27d5a
JR
238If the underlying BIO is \fBnon-blocking\fR, \fISSL_read()\fR will also return
239when the underlying BIO could not satisfy the needs of \fISSL_read()\fR
984263bc
MD
240to continue the operation. In this case a call to
241SSL_get_error(3) with the
a7d27d5a
JR
242return value of \fISSL_read()\fR will yield \fBSSL_ERROR_WANT_READ\fR or
243\fBSSL_ERROR_WANT_WRITE\fR. As at any time a re-negotiation is possible, a
984263bc
MD
244call to \fISSL_read()\fR can also cause write operations! The calling process
245then must repeat the call after taking appropriate action to satisfy the
a7d27d5a 246needs of \fISSL_read()\fR. The action depends on the underlying BIO. When using a
984263bc 247non-blocking socket, nothing is to be done, but \fIselect()\fR can be used to check
a7d27d5a
JR
248for the required condition. When using a buffering BIO, like a BIO pair, data
249must be written into or retrieved out of the BIO before being able to continue.
984263bc 250.SH "WARNING"
984263bc 251When an \fISSL_read()\fR operation has to be repeated because of
a7d27d5a 252\fBSSL_ERROR_WANT_READ\fR or \fBSSL_ERROR_WANT_WRITE\fR, it must be repeated
984263bc
MD
253with the same arguments.
254.SH "RETURN VALUES"
984263bc
MD
255The following return values can occur:
256.Ip ">0" 4
984263bc
MD
257The read operation was successful; the return value is the number of
258bytes actually read from the \s-1TLS/SSL\s0 connection.
259.Ip "0" 4
260The read operation was not successful. The reason may either be a clean
261shutdown due to a \*(L"close notify\*(R" alert sent by the peer (in which case
262the \s-1SSL_RECEIVED_SHUTDOWN\s0 flag in the ssl shutdown state is set
263(see SSL_shutdown(3),
264SSL_set_shutdown(3)). It is also possible, that
265the peer simply shut down the underlying transport and the shutdown is
266incomplete. Call \fISSL_get_error()\fR with the return value \fBret\fR to find out,
267whether an error occurred or the connection was shut down cleanly
268(\s-1SSL_ERROR_ZERO_RETURN\s0).
269.Sp
270SSLv2 (deprecated) does not support a shutdown alert protocol, so it can
271only be detected, whether the underlying connection was closed. It cannot
272be checked, whether the closure was initiated by the peer or by something
273else.
274.Ip "<0" 4
984263bc
MD
275The read operation was not successful, because either an error occurred
276or action must be taken by the calling process. Call \fISSL_get_error()\fR with the
277return value \fBret\fR to find out the reason.
278.SH "SEE ALSO"
984263bc
MD
279SSL_get_error(3), SSL_write(3),
280SSL_CTX_set_mode(3), SSL_CTX_new(3),
281SSL_connect(3), SSL_accept(3)
282SSL_set_connect_state(3),
283SSL_shutdown(3), SSL_set_shutdown(3),
284ssl(3), bio(3)
a7d27d5a
JR
285
286.rn }` ''
287.IX Title "SSL_read 3"
288.IX Name "SSL_read - read bytes from a TLS/SSL connection."
289
290.IX Header "NAME"
291
292.IX Header "SYNOPSIS"
293
294.IX Header "DESCRIPTION"
295
296.IX Header "NOTES"
297
298.IX Header "WARNING"
299
300.IX Header "RETURN VALUES"
301
302.IX Item ">0"
303
304.IX Item "0"
305
306.IX Item "<0"
307
308.IX Header "SEE ALSO"
309