lib/libcrypto/man/BIO_read.3

   1 .\"     $OpenBSD: BIO_read.3,v 1.5 2016/12/06 14:45:08 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: December 6 2016 $
  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
  87 attempts to read
  88 .Fa len
  89 bytes from BIO
  90 .Fa b
  91 and places the data in
  92 .Fa buf .
  93 .Pp
  94 .Fn BIO_gets
  95 performs the BIOs "gets" operation and places the data in
  96 .Fa buf .
  97 Usually this operation will attempt to read a line of data
  98 from the BIO of maximum length
  99 .Fa len No - 1 .
 100 There are exceptions to this however, for example
 101 .Fn BIO_gets
 102 on a digest BIO will calculate and return the digest
 103 and other BIOs may not support
 104 .Fn BIO_gets
 105 at all.
 106 The returned string is always NUL-terminated.
 107 .Pp
 108 .Fn BIO_write
 109 attempts to write
 110 .Fa len
 111 bytes from
 112 .Fa buf
 113 to BIO
 114 .Fa b .
 115 .Pp
 116 .Fn BIO_puts
 117 attempts to write a null terminated string
 118 .Fa buf
 119 to BIO
 120 .Fa b .
 121 .Pp
 122 One technique sometimes used with blocking sockets
 123 is to use a system call (such as
 124 .Xr select 2 ,
 125 .Xr poll 2
 126 or equivalent) to determine when data is available and then call
 127 .Xr read 2
 128 to read the data.
 129 The equivalent with BIOs (that is call
 130 .Xr select 2
 131 on the underlying I/O structure and then call
 132 .Fn BIO_read
 133 to read the data) should
 134 .Em not
 135 be used because a single call to
 136 .Fn BIO_read
 137 can cause several reads (and writes in the case of SSL BIOs)
 138 on the underlying I/O structure and may block as a result.
 139 Instead
 140 .Xr select 2
 141 (or equivalent) should be combined with non-blocking I/O
 142 so successive reads will request a retry instead of blocking.
 143 .Pp
 144 See
 145 .Xr BIO_should_retry 3
 146 for details of how to determine the cause of a retry and other I/O issues.
 147 .Pp
 148 If the
 149 .Fn BIO_gets
 150 function is not supported by a BIO then it is possible to
 151 work around this by adding a buffering BIO
 152 .Xr BIO_f_buffer 3
 153 to the chain.
 154 .Sh RETURN VALUES
 155 All these functions return either the amount of data successfully
 156 read or written (if the return value is positive) or that no data
 157 was successfully read or written if the result is 0 or -1.
 158 If the return value is -2, then the operation is not implemented
 159 in the specific BIO type.
 160 The trailing NUL is not included in the length returned by
 161 .Fn BIO_gets .
 162 .Pp
 163 A 0 or -1 return is not necessarily an indication of an error.
 164 In particular when the source/sink is non-blocking or of a certain type
 165 it may merely be an indication that no data is currently available and that
 166 the application should retry the operation later.
 167 .Sh SEE ALSO
 168 .Xr BIO_new 3 ,
 169 .Xr BIO_should_retry 3