1.\" $OpenBSD: BIO_read.3,v 1.8 2018/03/27 17:35:50 schwarze Exp $ 2.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 3.\" 4.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 5.\" Copyright (c) 2000, 2016 The OpenSSL Project. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in 16.\" the documentation and/or other materials provided with the 17.\" distribution. 18.\" 19.\" 3. All advertising materials mentioning features or use of this 20.\" software must display the following acknowledgment: 21.\" "This product includes software developed by the OpenSSL Project 22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 23.\" 24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 25.\" endorse or promote products derived from this software without 26.\" prior written permission. For written permission, please contact 27.\" openssl-core@openssl.org. 28.\" 29.\" 5. Products derived from this software may not be called "OpenSSL" 30.\" nor may "OpenSSL" appear in their names without prior written 31.\" permission of the OpenSSL Project. 32.\" 33.\" 6. Redistributions of any form whatsoever must retain the following 34.\" acknowledgment: 35.\" "This product includes software developed by the OpenSSL Project 36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 37.\" 38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 49.\" OF THE POSSIBILITY OF SUCH DAMAGE. 50.\" 51.Dd $Mdocdate: March 27 2018 $ 52.Dt BIO_READ 3 53.Os 54.Sh NAME 55.Nm BIO_read , 56.Nm BIO_gets , 57.Nm BIO_write , 58.Nm BIO_puts 59.Nd BIO I/O functions 60.Sh SYNOPSIS 61.In openssl/bio.h 62.Ft int 63.Fo BIO_read 64.Fa "BIO *b" 65.Fa "void *buf" 66.Fa "int len" 67.Fc 68.Ft int 69.Fo BIO_gets 70.Fa "BIO *b" 71.Fa "char *buf" 72.Fa "int size" 73.Fc 74.Ft int 75.Fo BIO_write 76.Fa "BIO *b" 77.Fa "const void *buf" 78.Fa "int len" 79.Fc 80.Ft int 81.Fo BIO_puts 82.Fa "BIO *b" 83.Fa "const char *buf" 84.Fc 85.Sh DESCRIPTION 86.Fn BIO_read 87attempts to read 88.Fa len 89bytes from BIO 90.Fa b 91and places the data in 92.Fa buf . 93.Pp 94.Fn BIO_gets 95performs the BIOs "gets" operation and places the data in 96.Fa buf . 97Usually this operation will attempt to read a line of data 98from the BIO of maximum length 99.Fa len No - 1 . 100There are exceptions to this however, for example 101.Fn BIO_gets 102on a digest BIO will calculate and return the digest 103and other BIOs may not support 104.Fn BIO_gets 105at all. 106The returned string is always NUL-terminated. 107.Pp 108.Fn BIO_write 109attempts to write 110.Fa len 111bytes from 112.Fa buf 113to BIO 114.Fa b . 115.Pp 116.Fn BIO_puts 117attempts to write a null terminated string 118.Fa buf 119to BIO 120.Fa b . 121.Pp 122One technique sometimes used with blocking sockets 123is to use a system call (such as 124.Xr select 2 , 125.Xr poll 2 126or equivalent) to determine when data is available and then call 127.Xr read 2 128to read the data. 129The equivalent with BIOs (that is call 130.Xr select 2 131on the underlying I/O structure and then call 132.Fn BIO_read 133to read the data) should 134.Em not 135be used because a single call to 136.Fn BIO_read 137can cause several reads (and writes in the case of SSL BIOs) 138on the underlying I/O structure and may block as a result. 139Instead 140.Xr select 2 141(or equivalent) should be combined with non-blocking I/O 142so successive reads will request a retry instead of blocking. 143.Pp 144See 145.Xr BIO_should_retry 3 146for details of how to determine the cause of a retry and other I/O issues. 147.Pp 148If the 149.Fn BIO_gets 150function is not supported by a BIO then it is possible to 151work around this by adding a buffering BIO 152.Xr BIO_f_buffer 3 153to the chain. 154.Sh RETURN VALUES 155All these functions return either the amount of data successfully 156read or written (if the return value is positive) or that no data 157was successfully read or written if the result is 0 or -1. 158If the return value is -2, then the operation is not implemented 159in the specific BIO type. 160The trailing NUL is not included in the length returned by 161.Fn BIO_gets . 162.Pp 163A 0 or -1 return is not necessarily an indication of an error. 164In particular when the source/sink is non-blocking or of a certain type 165it may merely be an indication that no data is currently available and that 166the application should retry the operation later. 167.Sh SEE ALSO 168.Xr BIO_meth_new 3 , 169.Xr BIO_new 3 , 170.Xr BIO_should_retry 3 171.Sh HISTORY 172.Fn BIO_read , 173.Fn BIO_gets , 174.Fn BIO_write , 175and 176.Fn BIO_puts 177first appeared in SSLeay 0.6.0 and have been available since 178.Ox 2.4 . 179