1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.37
| 1.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
|
2.\" 3.\" Standard preamble: 4.\" ========================================================================
| 2.\" 3.\" Standard preamble: 4.\" ========================================================================
|
5.de Sh \" Subsection heading 6.br 7.if t .Sp 8.ne 5 9.PP 10\fB\\$1\fR 11.PP 12..
| |
13.de Sp \" Vertical space (when we can't use .PP) 14.if t .sp .5v 15.if n .sp 16.. 17.de Vb \" Begin verbatim text 18.ft CW 19.nf 20.ne \\$1 21.. 22.de Ve \" End verbatim text 23.ft R 24.fi 25.. 26.\" Set up some character translations and predefined strings. \*(-- will 27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
| 5.de Sp \" Vertical space (when we can't use .PP) 6.if t .sp .5v 7.if n .sp 8.. 9.de Vb \" Begin verbatim text 10.ft CW 11.nf 12.ne \\$1 13.. 14.de Ve \" End verbatim text 15.ft R 16.fi 17.. 18.\" Set up some character translations and predefined strings. \*(-- will 19.\" 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<>. 32.tr \(*W-|\(bv\*(Tr
| 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-
|
33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' 34.ie n \{\ 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' "" 43'br\} 44.el\{\ 45. ds -- \|\(em\| 46. ds PI \(*p 47. ds L" `` 48. ds R" '' 49'br\} 50.\"
| 25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' 26.ie n \{\ 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' "" 35'br\} 36.el\{\ 37. ds -- \|\(em\| 38. ds PI \(*p 39. ds L" `` 40. ds R" '' 41'br\} 42.\"
|
| 43.\" Escape single quotes in literal strings from groff's Unicode transform. 44.ie \n(.g .ds Aq \(aq 45.el .ds Aq ' 46.\"
|
51.\" If the F register is turned on, we'll generate index entries on stderr for
| 47.\" 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
| 48.\" titles (.TH), headers (.SH), subsections (.SS), 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.
| 49.\" entries marked with X<> in POD. Of course, you'll have to process the 50.\" output yourself in some meaningful fashion.
|
55.if \nF \{\
| 51.ie \nF \{\
|
56. de IX 57. tm Index:\\$1\t\\n%\t"\\$2" 58.. 59. nr % 0 60. rr F 61.\}
| 52. de IX 53. tm Index:\\$1\t\\n%\t"\\$2" 54.. 55. nr % 0 56. rr F 57.\}
|
| 58.el \{\ 59. de IX 60.. 61.\}
|
62.\"
| 62.\"
|
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.\"
| |
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 71.if n \{\ 72. ds #H 0 73. ds #V .8m 74. ds #F .3m 75. ds #[ \f1 76. ds #] \fP 77.\} 78.if t \{\ 79. ds #H ((1u-(\\\\n(.fu%2u))*.13m) 80. ds #V .6m 81. ds #F 0 82. ds #[ \& 83. ds #] \& 84.\} 85. \" simple accents for nroff and troff 86.if n \{\ 87. ds ' \& 88. ds ` \& 89. ds ^ \& 90. ds , \& 91. ds ~ ~ 92. ds / 93.\} 94.if t \{\ 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' 101.\} 102. \" troff and (daisy-wheel) nroff accents 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 112. \" corrections for vroff 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' 115. \" for low resolution devices (crt and lpr) 116.if \n(.H>23 .if \n(.V>19 \ 117\{\ 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 127.\} 128.rm #[ #] #H #V #F C 129.\" ======================================================================== 130.\" 131.IX Title "BIO_read 3"
| 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 66.if n \{\ 67. ds #H 0 68. ds #V .8m 69. ds #F .3m 70. ds #[ \f1 71. ds #] \fP 72.\} 73.if t \{\ 74. ds #H ((1u-(\\\\n(.fu%2u))*.13m) 75. ds #V .6m 76. ds #F 0 77. ds #[ \& 78. ds #] \& 79.\} 80. \" simple accents for nroff and troff 81.if n \{\ 82. ds ' \& 83. ds ` \& 84. ds ^ \& 85. ds , \& 86. ds ~ ~ 87. ds / 88.\} 89.if t \{\ 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' 96.\} 97. \" troff and (daisy-wheel) nroff accents 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 107. \" corrections for vroff 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' 110. \" for low resolution devices (crt and lpr) 111.if \n(.H>23 .if \n(.V>19 \ 112\{\ 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 122.\} 123.rm #[ #] #H #V #F C 124.\" ======================================================================== 125.\" 126.IX Title "BIO_read 3"
|
132.TH BIO_read 3 "2010-03-24" "0.9.8n" "OpenSSL"
| 127.TH BIO_read 3 "2010-11-16" "0.9.8p" "OpenSSL" 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
|
133.SH "NAME" 134BIO_read, BIO_write, BIO_gets, BIO_puts \- BIO I/O functions 135.SH "SYNOPSIS" 136.IX Header "SYNOPSIS" 137.Vb 1 138\& #include <openssl/bio.h>
| 132.SH "NAME" 133BIO_read, BIO_write, BIO_gets, BIO_puts \- BIO I/O functions 134.SH "SYNOPSIS" 135.IX Header "SYNOPSIS" 136.Vb 1 137\& #include <openssl/bio.h>
|
139.Ve 140.PP 141.Vb 4
| 138\&
|
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" 148.IX Header "DESCRIPTION" 149\&\fIBIO_read()\fR attempts to read \fBlen\fR bytes from \s-1BIO\s0 \fBb\fR and places 150the data in \fBbuf\fR. 151.PP 152\&\fIBIO_gets()\fR performs the BIOs \*(L"gets\*(R" operation and places the data 153in \fBbuf\fR. Usually this operation will attempt to read a line of data 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 156return the digest and other BIOs may not support \fIBIO_gets()\fR at all. 157.PP 158\&\fIBIO_write()\fR attempts to write \fBlen\fR bytes from \fBbuf\fR to \s-1BIO\s0 \fBb\fR. 159.PP 160\&\fIBIO_puts()\fR attempts to write a null terminated string \fBbuf\fR to \s-1BIO\s0 \fBb\fR 161.SH "RETURN VALUES" 162.IX Header "RETURN VALUES" 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 166the operation is not implemented in the specific \s-1BIO\s0 type. 167.SH "NOTES" 168.IX Header "NOTES" 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 177\&\fIselect()\fR on the underlying I/O structure and then call \fIBIO_read()\fR to 178read the data) should \fBnot\fR be used because a single call to \fIBIO_read()\fR 179can cause several reads (and writes in the case of \s-1SSL\s0 BIOs) on the underlying 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 184See \fIBIO_should_retry\fR\|(3) for details of how to 185determine the cause of a retry and other I/O issues. 186.PP 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) 189to the chain. 190.SH "SEE ALSO" 191.IX Header "SEE ALSO" 192\&\fIBIO_should_retry\fR\|(3) 193.PP 194\&\s-1TBA\s0
| 139\& int BIO_read(BIO *b, void *buf, int len); 140\& int BIO_gets(BIO *b,char *buf, int size); 141\& int BIO_write(BIO *b, const void *buf, int len); 142\& int BIO_puts(BIO *b,const char *buf); 143.Ve 144.SH "DESCRIPTION" 145.IX Header "DESCRIPTION" 146\&\fIBIO_read()\fR attempts to read \fBlen\fR bytes from \s-1BIO\s0 \fBb\fR and places 147the data in \fBbuf\fR. 148.PP 149\&\fIBIO_gets()\fR performs the BIOs \*(L"gets\*(R" operation and places the data 150in \fBbuf\fR. Usually this operation will attempt to read a line of data 151from the \s-1BIO\s0 of maximum length \fBlen\fR. There are exceptions to this 152however, for example \fIBIO_gets()\fR on a digest \s-1BIO\s0 will calculate and 153return the digest and other BIOs may not support \fIBIO_gets()\fR at all. 154.PP 155\&\fIBIO_write()\fR attempts to write \fBlen\fR bytes from \fBbuf\fR to \s-1BIO\s0 \fBb\fR. 156.PP 157\&\fIBIO_puts()\fR attempts to write a null terminated string \fBbuf\fR to \s-1BIO\s0 \fBb\fR 158.SH "RETURN VALUES" 159.IX Header "RETURN VALUES" 160All these functions return either the amount of data successfully read or 161written (if the return value is positive) or that no data was successfully 162read or written if the result is 0 or \-1. If the return value is \-2 then 163the operation is not implemented in the specific \s-1BIO\s0 type. 164.SH "NOTES" 165.IX Header "NOTES" 166A 0 or \-1 return is not necessarily an indication of an error. In 167particular when the source/sink is non-blocking or of a certain type 168it may merely be an indication that no data is currently available and that 169the application should retry the operation later. 170.PP 171One technique sometimes used with blocking sockets is to use a system call 172(such as \fIselect()\fR, \fIpoll()\fR or equivalent) to determine when data is available 173and then call \fIread()\fR to read the data. The equivalent with BIOs (that is call 174\&\fIselect()\fR on the underlying I/O structure and then call \fIBIO_read()\fR to 175read the data) should \fBnot\fR be used because a single call to \fIBIO_read()\fR 176can cause several reads (and writes in the case of \s-1SSL\s0 BIOs) on the underlying 177I/O structure and may block as a result. Instead \fIselect()\fR (or equivalent) 178should be combined with non blocking I/O so successive reads will request 179a retry instead of blocking. 180.PP 181See \fIBIO_should_retry\fR\|(3) for details of how to 182determine the cause of a retry and other I/O issues. 183.PP 184If the \fIBIO_gets()\fR function is not supported by a \s-1BIO\s0 then it possible to 185work around this by adding a buffering \s-1BIO\s0 \fIBIO_f_buffer\fR\|(3) 186to the chain. 187.SH "SEE ALSO" 188.IX Header "SEE ALSO" 189\&\fIBIO_should_retry\fR\|(3) 190.PP 191\&\s-1TBA\s0
|