secure/lib/libcrypto/man/man3/BIO_ctrl.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   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
  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-
  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 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "BIO_CTRL 3"
 136 .TH BIO_CTRL 3 "2021-02-16" "1.1.1j" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset, BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close, BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending, BIO_get_info_callback, BIO_set_info_callback, BIO_info_cb, BIO_get_ktls_send, BIO_get_ktls_recv \&\- BIO control operations
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/bio.h>
 147 \&
 148 \& typedef int BIO_info_cb(BIO *b, int state, int res);
 149 \&
 150 \& long BIO_ctrl(BIO *bp, int cmd, long larg, void *parg);
 151 \& long BIO_callback_ctrl(BIO *b, int cmd, BIO_info_cb *cb);
 152 \& char *BIO_ptr_ctrl(BIO *bp, int cmd, long larg);
 153 \& long BIO_int_ctrl(BIO *bp, int cmd, long larg, int iarg);
 154 \&
 155 \& int BIO_reset(BIO *b);
 156 \& int BIO_seek(BIO *b, int ofs);
 157 \& int BIO_tell(BIO *b);
 158 \& int BIO_flush(BIO *b);
 159 \& int BIO_eof(BIO *b);
 160 \& int BIO_set_close(BIO *b, long flag);
 161 \& int BIO_get_close(BIO *b);
 162 \& int BIO_pending(BIO *b);
 163 \& int BIO_wpending(BIO *b);
 164 \& size_t BIO_ctrl_pending(BIO *b);
 165 \& size_t BIO_ctrl_wpending(BIO *b);
 166 \&
 167 \& int BIO_get_info_callback(BIO *b, BIO_info_cb **cbp);
 168 \& int BIO_set_info_callback(BIO *b, BIO_info_cb *cb);
 169 \&
 170 \& int BIO_get_ktls_send(BIO *b);
 171 \& int BIO_get_ktls_recv(BIO *b);
 172 .Ve
 173 .SH "DESCRIPTION"
 174 .IX Header "DESCRIPTION"
 175 \&\fBBIO_ctrl()\fR, \fBBIO_callback_ctrl()\fR, \fBBIO_ptr_ctrl()\fR and \fBBIO_int_ctrl()\fR
 176 are \s-1BIO\s0 \*(L"control\*(R" operations taking arguments of various types.
 177 These functions are not normally called directly, various macros
 178 are used instead. The standard macros are described below, macros
 179 specific to a particular type of \s-1BIO\s0 are described in the specific
 180 BIOs manual page as well as any special features of the standard
 181 calls.
 182 .PP
 183 \&\fBBIO_reset()\fR typically resets a \s-1BIO\s0 to some initial state, in the case
 184 of file related BIOs for example it rewinds the file pointer to the
 185 start of the file.
 186 .PP
 187 \&\fBBIO_seek()\fR resets a file related \s-1BIO\s0's (that is file descriptor and
 188 \&\s-1FILE\s0 BIOs) file position pointer to \fBofs\fR bytes from start of file.
 189 .PP
 190 \&\fBBIO_tell()\fR returns the current file position of a file related \s-1BIO.\s0
 191 .PP
 192 \&\fBBIO_flush()\fR normally writes out any internally buffered data, in some
 193 cases it is used to signal \s-1EOF\s0 and that no more data will be written.
 194 .PP
 195 \&\fBBIO_eof()\fR returns 1 if the \s-1BIO\s0 has read \s-1EOF,\s0 the precise meaning of
 196 \&\*(L"\s-1EOF\*(R"\s0 varies according to the \s-1BIO\s0 type.
 197 .PP
 198 \&\fBBIO_set_close()\fR sets the \s-1BIO\s0 \fBb\fR close flag to \fBflag\fR. \fBflag\fR can
 199 take the value \s-1BIO_CLOSE\s0 or \s-1BIO_NOCLOSE.\s0 Typically \s-1BIO_CLOSE\s0 is used
 200 in a source/sink \s-1BIO\s0 to indicate that the underlying I/O stream should
 201 be closed when the \s-1BIO\s0 is freed.
 202 .PP
 203 \&\fBBIO_get_close()\fR returns the BIOs close flag.
 204 .PP
 205 \&\fBBIO_pending()\fR, \fBBIO_ctrl_pending()\fR, \fBBIO_wpending()\fR and \fBBIO_ctrl_wpending()\fR
 206 return the number of pending characters in the BIOs read and write buffers.
 207 Not all BIOs support these calls. \fBBIO_ctrl_pending()\fR and \fBBIO_ctrl_wpending()\fR
 208 return a size_t type and are functions, \fBBIO_pending()\fR and \fBBIO_wpending()\fR are
 209 macros which call \fBBIO_ctrl()\fR.
 210 .PP
 211 \&\fBBIO_get_ktls_send()\fR returns 1 if the \s-1BIO\s0 is using the Kernel \s-1TLS\s0 data-path for
 212 sending. Otherwise, it returns zero.
 213 \&\fBBIO_get_ktls_recv()\fR returns 1 if the \s-1BIO\s0 is using the Kernel \s-1TLS\s0 data-path for
 214 receiving. Otherwise, it returns zero.
 215 .SH "RETURN VALUES"
 216 .IX Header "RETURN VALUES"
 217 \&\fBBIO_reset()\fR normally returns 1 for success and 0 or \-1 for failure. File
 218 BIOs are an exception, they return 0 for success and \-1 for failure.
 219 .PP
 220 \&\fBBIO_seek()\fR and \fBBIO_tell()\fR both return the current file position on success
 221 and \-1 for failure, except file BIOs which for \fBBIO_seek()\fR always return 0
 222 for success and \-1 for failure.
 223 .PP
 224 \&\fBBIO_flush()\fR returns 1 for success and 0 or \-1 for failure.
 225 .PP
 226 \&\fBBIO_eof()\fR returns 1 if \s-1EOF\s0 has been reached 0 otherwise.
 227 .PP
 228 \&\fBBIO_set_close()\fR always returns 1.
 229 .PP
 230 \&\fBBIO_get_close()\fR returns the close flag value: \s-1BIO_CLOSE\s0 or \s-1BIO_NOCLOSE.\s0
 231 .PP
 232 \&\fBBIO_pending()\fR, \fBBIO_ctrl_pending()\fR, \fBBIO_wpending()\fR and \fBBIO_ctrl_wpending()\fR
 233 return the amount of pending data.
 234 .PP
 235 \&\fBBIO_get_ktls_send()\fR returns 1 if the \s-1BIO\s0 is using the Kernel \s-1TLS\s0 data-path for
 236 sending. Otherwise, it returns zero.
 237 \&\fBBIO_get_ktls_recv()\fR returns 1 if the \s-1BIO\s0 is using the Kernel \s-1TLS\s0 data-path for
 238 receiving. Otherwise, it returns zero.
 239 .SH "NOTES"
 240 .IX Header "NOTES"
 241 \&\fBBIO_flush()\fR, because it can write data may return 0 or \-1 indicating
 242 that the call should be retried later in a similar manner to \fBBIO_write_ex()\fR.
 243 The \fBBIO_should_retry()\fR call should be used and appropriate action taken
 244 is the call fails.
 245 .PP
 246 The return values of \fBBIO_pending()\fR and \fBBIO_wpending()\fR may not reliably
 247 determine the amount of pending data in all cases. For example in the
 248 case of a file \s-1BIO\s0 some data may be available in the \s-1FILE\s0 structures
 249 internal buffers but it is not possible to determine this in a
 250 portably way. For other types of \s-1BIO\s0 they may not be supported.
 251 .PP
 252 Filter BIOs if they do not internally handle a particular \fBBIO_ctrl()\fR
 253 operation usually pass the operation to the next \s-1BIO\s0 in the chain.
 254 This often means there is no need to locate the required \s-1BIO\s0 for
 255 a particular operation, it can be called on a chain and it will
 256 be automatically passed to the relevant \s-1BIO.\s0 However, this can cause
 257 unexpected results: for example no current filter BIOs implement
 258 \&\fBBIO_seek()\fR, but this may still succeed if the chain ends in a \s-1FILE\s0
 259 or file descriptor \s-1BIO.\s0
 260 .PP
 261 Source/sink BIOs return an 0 if they do not recognize the \fBBIO_ctrl()\fR
 262 operation.
 263 .SH "BUGS"
 264 .IX Header "BUGS"
 265 Some of the return values are ambiguous and care should be taken. In
 266 particular a return value of 0 can be returned if an operation is not
 267 supported, if an error occurred, if \s-1EOF\s0 has not been reached and in
 268 the case of \fBBIO_seek()\fR on a file \s-1BIO\s0 for a successful operation.
 269 .SH "HISTORY"
 270 .IX Header "HISTORY"
 271 The \fBBIO_get_ktls_send()\fR and \fBBIO_get_ktls_recv()\fR functions were added in
 272 OpenSSL 3.0.0.
 273 .SH "COPYRIGHT"
 274 .IX Header "COPYRIGHT"
 275 Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved.
 276 .PP
 277 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 278 this file except in compliance with the License.  You can obtain a copy
 279 in the file \s-1LICENSE\s0 in the source distribution or at
 280 <https://www.openssl.org/source/license.html>.