secure/lib/libcrypto/man/BIO_meth_new.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  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_METH_NEW 3"
 132 .TH BIO_METH_NEW 3 "2018-11-20" "1.1.1a" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 BIO_get_new_index, BIO_meth_new, BIO_meth_free, BIO_meth_get_read_ex, BIO_meth_set_read_ex, BIO_meth_get_write_ex, BIO_meth_set_write_ex, BIO_meth_get_write, BIO_meth_set_write, BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts, BIO_meth_set_puts, BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl, BIO_meth_set_ctrl, BIO_meth_get_create, BIO_meth_set_create, BIO_meth_get_destroy, BIO_meth_set_destroy, BIO_meth_get_callback_ctrl, BIO_meth_set_callback_ctrl \- Routines to build up BIO methods
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/bio.h>
 143 \&
 144 \& int BIO_get_new_index(void);
 145 \&
 146 \& BIO_METHOD *BIO_meth_new(int type, const char *name);
 147 \&
 148 \& void BIO_meth_free(BIO_METHOD *biom);
 149 \&
 150 \& int (*BIO_meth_get_write_ex(const BIO_METHOD *biom))(BIO *, const char *, size_t,
 151 \&                                                size_t *);
 152 \& int (*BIO_meth_get_write(const BIO_METHOD *biom))(BIO *, const char *, int);
 153 \& int BIO_meth_set_write_ex(BIO_METHOD *biom,
 154 \&                           int (*bwrite)(BIO *, const char *, size_t, size_t *));
 155 \& int BIO_meth_set_write(BIO_METHOD *biom,
 156 \&                        int (*write)(BIO *, const char *, int));
 157 \&
 158 \& int (*BIO_meth_get_read_ex(const BIO_METHOD *biom))(BIO *, char *, size_t, size_t *);
 159 \& int (*BIO_meth_get_read(const BIO_METHOD *biom))(BIO *, char *, int);
 160 \& int BIO_meth_set_read_ex(BIO_METHOD *biom,
 161 \&                          int (*bread)(BIO *, char *, size_t, size_t *));
 162 \& int BIO_meth_set_read(BIO_METHOD *biom, int (*read)(BIO *, char *, int));
 163 \&
 164 \& int (*BIO_meth_get_puts(const BIO_METHOD *biom))(BIO *, const char *);
 165 \& int BIO_meth_set_puts(BIO_METHOD *biom, int (*puts)(BIO *, const char *));
 166 \&
 167 \& int (*BIO_meth_get_gets(const BIO_METHOD *biom))(BIO *, char *, int);
 168 \& int BIO_meth_set_gets(BIO_METHOD *biom,
 169 \&                       int (*gets)(BIO *, char *, int));
 170 \&
 171 \& long (*BIO_meth_get_ctrl(const BIO_METHOD *biom))(BIO *, int, long, void *);
 172 \& int BIO_meth_set_ctrl(BIO_METHOD *biom,
 173 \&                       long (*ctrl)(BIO *, int, long, void *));
 174 \&
 175 \& int (*BIO_meth_get_create(const BIO_METHOD *bion))(BIO *);
 176 \& int BIO_meth_set_create(BIO_METHOD *biom, int (*create)(BIO *));
 177 \&
 178 \& int (*BIO_meth_get_destroy(const BIO_METHOD *biom))(BIO *);
 179 \& int BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy)(BIO *));
 180 \&
 181 \& long (*BIO_meth_get_callback_ctrl(const BIO_METHOD *biom))(BIO *, int, BIO_info_cb *);
 182 \& int BIO_meth_set_callback_ctrl(BIO_METHOD *biom,
 183 \&                                long (*callback_ctrl)(BIO *, int, BIO_info_cb *));
 184 .Ve
 185 .SH "DESCRIPTION"
 186 .IX Header "DESCRIPTION"
 187 The \fB\s-1BIO_METHOD\s0\fR type is a structure used for the implementation of new \s-1BIO\s0
 188 types. It provides a set of functions used by OpenSSL for the implementation
 189 of the various \s-1BIO\s0 capabilities. See the bio page for more information.
 190 .PP
 191 \&\fIBIO_meth_new()\fR creates a new \fB\s-1BIO_METHOD\s0\fR structure. It should be given a
 192 unique integer \fBtype\fR and a string that represents its \fBname\fR.
 193 Use \fIBIO_get_new_index()\fR to get the value for \fBtype\fR.
 194 .PP
 195 The set of
 196 standard OpenSSL provided \s-1BIO\s0 types is provided in \fBbio.h\fR. Some examples
 197 include \fB\s-1BIO_TYPE_BUFFER\s0\fR and \fB\s-1BIO_TYPE_CIPHER\s0\fR. Filter BIOs should have a
 198 type which have the \*(L"filter\*(R" bit set (\fB\s-1BIO_TYPE_FILTER\s0\fR). Source/sink BIOs
 199 should have the \*(L"source/sink\*(R" bit set (\fB\s-1BIO_TYPE_SOURCE_SINK\s0\fR). File descriptor
 200 based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the
 201 \&\*(L"descriptor\*(R" bit set (\fB\s-1BIO_TYPE_DESCRIPTOR\s0\fR). See the BIO_find_type page for
 202 more information.
 203 .PP
 204 \&\fIBIO_meth_free()\fR destroys a \fB\s-1BIO_METHOD\s0\fR structure and frees up any memory
 205 associated with it.
 206 .PP
 207 \&\fIBIO_meth_get_write_ex()\fR and \fIBIO_meth_set_write_ex()\fR get and set the function
 208 used for writing arbitrary length data to the \s-1BIO\s0 respectively. This function
 209 will be called in response to the application calling \fIBIO_write_ex()\fR or
 210 \&\fIBIO_write()\fR. The parameters for the function have the same meaning as for
 211 \&\fIBIO_write_ex()\fR. Older code may call \fIBIO_meth_get_write()\fR and
 212 \&\fIBIO_meth_set_write()\fR instead. Applications should not call both
 213 \&\fIBIO_meth_set_write_ex()\fR and \fIBIO_meth_set_write()\fR or call \fIBIO_meth_get_write()\fR
 214 when the function was set with \fIBIO_meth_set_write_ex()\fR.
 215 .PP
 216 \&\fIBIO_meth_get_read_ex()\fR and \fIBIO_meth_set_read_ex()\fR get and set the function used
 217 for reading arbitrary length data from the \s-1BIO\s0 respectively. This function will
 218 be called in response to the application calling \fIBIO_read_ex()\fR or \fIBIO_read()\fR.
 219 The parameters for the function have the same meaning as for \fIBIO_read_ex()\fR.
 220 Older code may call \fIBIO_meth_get_read()\fR and \fIBIO_meth_set_read()\fR instead.
 221 Applications should not call both \fIBIO_meth_set_read_ex()\fR and \fIBIO_meth_set_read()\fR
 222 or call \fIBIO_meth_get_read()\fR when the function was set with
 223 \&\fIBIO_meth_set_read_ex()\fR.
 224 .PP
 225 \&\fIBIO_meth_get_puts()\fR and \fIBIO_meth_set_puts()\fR get and set the function used for
 226 writing a \s-1NULL\s0 terminated string to the \s-1BIO\s0 respectively. This function will be
 227 called in response to the application calling \fIBIO_puts()\fR. The parameters for
 228 the function have the same meaning as for \fIBIO_puts()\fR.
 229 .PP
 230 \&\fIBIO_meth_get_gets()\fR and \fIBIO_meth_set_gets()\fR get and set the function typically
 231 used for reading a line of data from the \s-1BIO\s0 respectively (see the \fIBIO_gets\fR\|(3)
 232 page for more information). This function will be called in response to the
 233 application calling \fIBIO_gets()\fR. The parameters for the function have the same
 234 meaning as for \fIBIO_gets()\fR.
 235 .PP
 236 \&\fIBIO_meth_get_ctrl()\fR and \fIBIO_meth_set_ctrl()\fR get and set the function used for
 237 processing ctrl messages in the \s-1BIO\s0 respectively. See the BIO_ctrl page for
 238 more information. This function will be called in response to the application
 239 calling \fIBIO_ctrl()\fR. The parameters for the function have the same meaning as for
 240 \&\fIBIO_ctrl()\fR.
 241 .PP
 242 \&\fIBIO_meth_get_create()\fR and \fIBIO_meth_set_create()\fR get and set the function used
 243 for creating a new instance of the \s-1BIO\s0 respectively. This function will be
 244 called in response to the application calling \fIBIO_new()\fR and passing
 245 in a pointer to the current \s-1BIO_METHOD.\s0 The \fIBIO_new()\fR function will allocate the
 246 memory for the new \s-1BIO,\s0 and a pointer to this newly allocated structure will
 247 be passed as a parameter to the function.
 248 .PP
 249 \&\fIBIO_meth_get_destroy()\fR and \fIBIO_meth_set_destroy()\fR get and set the function used
 250 for destroying an instance of a \s-1BIO\s0 respectively. This function will be
 251 called in response to the application calling \fIBIO_free()\fR. A pointer to the \s-1BIO\s0
 252 to be destroyed is passed as a parameter. The destroy function should be used
 253 for \s-1BIO\s0 specific clean up. The memory for the \s-1BIO\s0 itself should not be freed by
 254 this function.
 255 .PP
 256 \&\fIBIO_meth_get_callback_ctrl()\fR and \fIBIO_meth_set_callback_ctrl()\fR get and set the
 257 function used for processing callback ctrl messages in the \s-1BIO\s0 respectively. See
 258 the \fIBIO_callback_ctrl\fR\|(3) page for more information. This function will be called
 259 in response to the application calling \fIBIO_callback_ctrl()\fR. The parameters for
 260 the function have the same meaning as for \fIBIO_callback_ctrl()\fR.
 261 .SH "RETURN VALUES"
 262 .IX Header "RETURN VALUES"
 263 \&\fIBIO_get_new_index()\fR returns the new \s-1BIO\s0 type value or \-1 if an error occurred.
 264 .PP
 265 BIO_meth_new(int type, const char *name) returns a valid \fB\s-1BIO_METHOD\s0\fR or \s-1NULL\s0
 266 if an error occurred.
 267 .PP
 268 The \fBBIO_meth_set\fR functions return 1 on success or 0 on error.
 269 .PP
 270 The \fBBIO_meth_get\fR functions return the corresponding function pointers.
 271 .SH "SEE ALSO"
 272 .IX Header "SEE ALSO"
 273 bio, BIO_find_type, BIO_ctrl, BIO_read_ex, BIO_new
 274 .SH "HISTORY"
 275 .IX Header "HISTORY"
 276 The functions described here were added in OpenSSL 1.1.0.
 277 .SH "COPYRIGHT"
 278 .IX Header "COPYRIGHT"
 279 Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved.
 280 .PP
 281 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 282 this file except in compliance with the License.  You can obtain a copy
 283 in the file \s-1LICENSE\s0 in the source distribution or at
 284 <https://www.openssl.org/source/license.html>.