Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / lib / libssl / man / SSL_read.3
CommitLineData
e3261593 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
e056f0e0
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
e056f0e0 5.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
6.if t .sp .5v
7.if n .sp
8..
e056f0e0 9.de Vb \" Begin verbatim text
984263bc
MD
10.ft CW
11.nf
12.ne \\$1
13..
e056f0e0 14.de Ve \" End verbatim text
984263bc 15.ft R
984263bc
MD
16.fi
17..
e056f0e0
JR
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
20.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
e056f0e0 25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 26.ie n \{\
e056f0e0
JR
27. ds -- \(*W-
28. ds PI pi
29. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31. ds L" ""
32. ds R" ""
33. ds C` ""
34. ds C' ""
984263bc
MD
35'br\}
36.el\{\
e056f0e0
JR
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
984263bc 41'br\}
e056f0e0 42.\"
e257b235
PA
43.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq
45.el .ds Aq '
46.\"
e056f0e0 47.\" If the F register is turned on, we'll generate index entries on stderr for
01185282 48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
e056f0e0
JR
49.\" entries marked with X<> in POD. Of course, you'll have to process the
50.\" output yourself in some meaningful fashion.
e257b235 51.ie \nF \{\
e056f0e0
JR
52. de IX
53. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 54..
e056f0e0
JR
55. nr % 0
56. rr F
984263bc 57.\}
e257b235
PA
58.el \{\
59. de IX
60..
61.\}
aac4ff6f 62.\"
e056f0e0
JR
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear. Run. Save yourself. No user-serviceable parts.
65. \" fudge factors for nroff and troff
984263bc 66.if n \{\
e056f0e0
JR
67. ds #H 0
68. ds #V .8m
69. ds #F .3m
70. ds #[ \f1
71. ds #] \fP
984263bc
MD
72.\}
73.if t \{\
e056f0e0
JR
74. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75. ds #V .6m
76. ds #F 0
77. ds #[ \&
78. ds #] \&
984263bc 79.\}
e056f0e0 80. \" simple accents for nroff and troff
984263bc 81.if n \{\
e056f0e0
JR
82. ds ' \&
83. ds ` \&
84. ds ^ \&
85. ds , \&
86. ds ~ ~
87. ds /
984263bc
MD
88.\}
89.if t \{\
e056f0e0
JR
90. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 96.\}
e056f0e0 97. \" troff and (daisy-wheel) nroff accents
984263bc
MD
98.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105.ds ae a\h'-(\w'a'u*4/10)'e
106.ds Ae A\h'-(\w'A'u*4/10)'E
e056f0e0 107. \" corrections for vroff
984263bc
MD
108.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
e056f0e0 110. \" for low resolution devices (crt and lpr)
984263bc
MD
111.if \n(.H>23 .if \n(.V>19 \
112\{\
e056f0e0
JR
113. ds : e
114. ds 8 ss
115. ds o a
116. ds d- d\h'-1'\(ga
117. ds D- D\h'-1'\(hy
118. ds th \o'bp'
119. ds Th \o'LP'
120. ds ae ae
121. ds Ae AE
984263bc
MD
122.\}
123.rm #[ #] #H #V #F C
e056f0e0
JR
124.\" ========================================================================
125.\"
126.IX Title "SSL_read 3"
e3261593 127.TH SSL_read 3 "2012-01-04" "1.0.0f" "OpenSSL"
e257b235
PA
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents.
130.if n .ad l
131.nh
984263bc 132.SH "NAME"
a7d27d5a 133SSL_read \- read bytes from a TLS/SSL connection.
984263bc 134.SH "SYNOPSIS"
e056f0e0 135.IX Header "SYNOPSIS"
984263bc
MD
136.Vb 1
137\& #include <openssl/ssl.h>
e257b235 138\&
984263bc
MD
139\& int SSL_read(SSL *ssl, void *buf, int num);
140.Ve
141.SH "DESCRIPTION"
e056f0e0
JR
142.IX Header "DESCRIPTION"
143\&\fISSL_read()\fR tries to read \fBnum\fR bytes from the specified \fBssl\fR into the
984263bc
MD
144buffer \fBbuf\fR.
145.SH "NOTES"
e056f0e0
JR
146.IX Header "NOTES"
147If necessary, \fISSL_read()\fR will negotiate a \s-1TLS/SSL\s0 session, if
148not already explicitly performed by \fISSL_connect\fR\|(3) or
149\&\fISSL_accept\fR\|(3). If the
e257b235 150peer requests a re-negotiation, it will be performed transparently during
984263bc 151the \fISSL_read()\fR operation. The behaviour of \fISSL_read()\fR depends on the
e257b235 152underlying \s-1BIO\s0.
984263bc
MD
153.PP
154For the transparent negotiation to succeed, the \fBssl\fR must have been
155initialized to client or server mode. This is being done by calling
e056f0e0
JR
156\&\fISSL_set_connect_state\fR\|(3) or \fISSL_set_accept_state()\fR
157before the first call to an \fISSL_read()\fR or \fISSL_write\fR\|(3)
984263bc
MD
158function.
159.PP
e056f0e0 160\&\fISSL_read()\fR works based on the \s-1SSL/TLS\s0 records. The data are received in
984263bc
MD
161records (with a maximum record size of 16kB for SSLv3/TLSv1). Only when a
162record has been completely received, it can be processed (decryption and
163check of integrity). Therefore data that was not retrieved at the last
e056f0e0 164call of \fISSL_read()\fR can still be buffered inside the \s-1SSL\s0 layer and will be
984263bc
MD
165retrieved on the next call to \fISSL_read()\fR. If \fBnum\fR is higher than the
166number of bytes buffered, \fISSL_read()\fR will return with the bytes buffered.
167If no more bytes are in the buffer, \fISSL_read()\fR will trigger the processing
168of the next record. Only when the record has been received and processed
169completely, \fISSL_read()\fR will return reporting success. At most the contents
e056f0e0
JR
170of the record will be returned. As the size of an \s-1SSL/TLS\s0 record may exceed
171the maximum packet size of the underlying transport (e.g. \s-1TCP\s0), it may
984263bc
MD
172be necessary to read several packets from the transport layer before the
173record is complete and \fISSL_read()\fR can succeed.
174.PP
e056f0e0 175If the underlying \s-1BIO\s0 is \fBblocking\fR, \fISSL_read()\fR will only return, once the
984263bc 176read operation has been finished or an error occurred, except when a
e056f0e0
JR
177renegotiation take place, in which case a \s-1SSL_ERROR_WANT_READ\s0 may occur.
178This behaviour can be controlled with the \s-1SSL_MODE_AUTO_RETRY\s0 flag of the
179\&\fISSL_CTX_set_mode\fR\|(3) call.
984263bc 180.PP
e056f0e0
JR
181If the underlying \s-1BIO\s0 is \fBnon-blocking\fR, \fISSL_read()\fR will also return
182when the underlying \s-1BIO\s0 could not satisfy the needs of \fISSL_read()\fR
984263bc 183to continue the operation. In this case a call to
e056f0e0
JR
184\&\fISSL_get_error\fR\|(3) with the
185return value of \fISSL_read()\fR will yield \fB\s-1SSL_ERROR_WANT_READ\s0\fR or
186\&\fB\s-1SSL_ERROR_WANT_WRITE\s0\fR. As at any time a re-negotiation is possible, a
984263bc
MD
187call to \fISSL_read()\fR can also cause write operations! The calling process
188then must repeat the call after taking appropriate action to satisfy the
e056f0e0 189needs of \fISSL_read()\fR. The action depends on the underlying \s-1BIO\s0. When using a
984263bc 190non-blocking socket, nothing is to be done, but \fIselect()\fR can be used to check
e056f0e0
JR
191for the required condition. When using a buffering \s-1BIO\s0, like a \s-1BIO\s0 pair, data
192must be written into or retrieved out of the \s-1BIO\s0 before being able to continue.
18ed9402
PA
193.PP
194\&\fISSL_pending\fR\|(3) can be used to find out whether there
195are buffered bytes available for immediate retrieval. In this case
196\&\fISSL_read()\fR can be called without blocking or actually receiving new
197data from the underlying socket.
984263bc 198.SH "WARNING"
e056f0e0 199.IX Header "WARNING"
984263bc 200When an \fISSL_read()\fR operation has to be repeated because of
e056f0e0 201\&\fB\s-1SSL_ERROR_WANT_READ\s0\fR or \fB\s-1SSL_ERROR_WANT_WRITE\s0\fR, it must be repeated
984263bc
MD
202with the same arguments.
203.SH "RETURN VALUES"
e056f0e0 204.IX Header "RETURN VALUES"
984263bc 205The following return values can occur:
e056f0e0
JR
206.IP ">0" 4
207.IX Item ">0"
984263bc
MD
208The read operation was successful; the return value is the number of
209bytes actually read from the \s-1TLS/SSL\s0 connection.
e056f0e0 210.IP "0" 4
984263bc
MD
211The read operation was not successful. The reason may either be a clean
212shutdown due to a \*(L"close notify\*(R" alert sent by the peer (in which case
213the \s-1SSL_RECEIVED_SHUTDOWN\s0 flag in the ssl shutdown state is set
e056f0e0
JR
214(see \fISSL_shutdown\fR\|(3),
215\&\fISSL_set_shutdown\fR\|(3)). It is also possible, that
984263bc
MD
216the peer simply shut down the underlying transport and the shutdown is
217incomplete. Call \fISSL_get_error()\fR with the return value \fBret\fR to find out,
218whether an error occurred or the connection was shut down cleanly
219(\s-1SSL_ERROR_ZERO_RETURN\s0).
220.Sp
221SSLv2 (deprecated) does not support a shutdown alert protocol, so it can
222only be detected, whether the underlying connection was closed. It cannot
223be checked, whether the closure was initiated by the peer or by something
224else.
e056f0e0
JR
225.IP "<0" 4
226.IX Item "<0"
984263bc
MD
227The read operation was not successful, because either an error occurred
228or action must be taken by the calling process. Call \fISSL_get_error()\fR with the
229return value \fBret\fR to find out the reason.
230.SH "SEE ALSO"
a7d27d5a 231.IX Header "SEE ALSO"
e056f0e0
JR
232\&\fISSL_get_error\fR\|(3), \fISSL_write\fR\|(3),
233\&\fISSL_CTX_set_mode\fR\|(3), \fISSL_CTX_new\fR\|(3),
234\&\fISSL_connect\fR\|(3), \fISSL_accept\fR\|(3)
235\&\fISSL_set_connect_state\fR\|(3),
18ed9402 236\&\fISSL_pending\fR\|(3),
e056f0e0
JR
237\&\fISSL_shutdown\fR\|(3), \fISSL_set_shutdown\fR\|(3),
238\&\fIssl\fR\|(3), \fIbio\fR\|(3)