secure/lib/libcrypto/man/BIO_meth_new.3

   1 .\" Automatically generated by Pod::Man 4.10 (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 .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_METH_NEW 3"
 136 .TH BIO_METH_NEW 3 "2019-02-26" "1.1.1b" "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_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
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/bio.h>
 147 \&
 148 \& int BIO_get_new_index(void);
 149 \&
 150 \& BIO_METHOD *BIO_meth_new(int type, const char *name);
 151 \&
 152 \& void BIO_meth_free(BIO_METHOD *biom);
 153 \&
 154 \& int (*BIO_meth_get_write_ex(const BIO_METHOD *biom))(BIO *, const char *, size_t,
 155 \&                                                size_t *);
 156 \& int (*BIO_meth_get_write(const BIO_METHOD *biom))(BIO *, const char *, int);
 157 \& int BIO_meth_set_write_ex(BIO_METHOD *biom,
 158 \&                           int (*bwrite)(BIO *, const char *, size_t, size_t *));
 159 \& int BIO_meth_set_write(BIO_METHOD *biom,
 160 \&                        int (*write)(BIO *, const char *, int));
 161 \&
 162 \& int (*BIO_meth_get_read_ex(const BIO_METHOD *biom))(BIO *, char *, size_t, size_t *);
 163 \& int (*BIO_meth_get_read(const BIO_METHOD *biom))(BIO *, char *, int);
 164 \& int BIO_meth_set_read_ex(BIO_METHOD *biom,
 165 \&                          int (*bread)(BIO *, char *, size_t, size_t *));
 166 \& int BIO_meth_set_read(BIO_METHOD *biom, int (*read)(BIO *, char *, int));
 167 \&
 168 \& int (*BIO_meth_get_puts(const BIO_METHOD *biom))(BIO *, const char *);
 169 \& int BIO_meth_set_puts(BIO_METHOD *biom, int (*puts)(BIO *, const char *));
 170 \&
 171 \& int (*BIO_meth_get_gets(const BIO_METHOD *biom))(BIO *, char *, int);
 172 \& int BIO_meth_set_gets(BIO_METHOD *biom,
 173 \&                       int (*gets)(BIO *, char *, int));
 174 \&
 175 \& long (*BIO_meth_get_ctrl(const BIO_METHOD *biom))(BIO *, int, long, void *);
 176 \& int BIO_meth_set_ctrl(BIO_METHOD *biom,
 177 \&                       long (*ctrl)(BIO *, int, long, void *));
 178 \&
 179 \& int (*BIO_meth_get_create(const BIO_METHOD *bion))(BIO *);
 180 \& int BIO_meth_set_create(BIO_METHOD *biom, int (*create)(BIO *));
 181 \&
 182 \& int (*BIO_meth_get_destroy(const BIO_METHOD *biom))(BIO *);
 183 \& int BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy)(BIO *));
 184 \&
 185 \& long (*BIO_meth_get_callback_ctrl(const BIO_METHOD *biom))(BIO *, int, BIO_info_cb *);
 186 \& int BIO_meth_set_callback_ctrl(BIO_METHOD *biom,
 187 \&                                long (*callback_ctrl)(BIO *, int, BIO_info_cb *));
 188 .Ve
 189 .SH "DESCRIPTION"
 190 .IX Header "DESCRIPTION"
 191 The \fB\s-1BIO_METHOD\s0\fR type is a structure used for the implementation of new \s-1BIO\s0
 192 types. It provides a set of functions used by OpenSSL for the implementation
 193 of the various \s-1BIO\s0 capabilities. See the bio page for more information.
 194 .PP
 195 \&\fBBIO_meth_new()\fR creates a new \fB\s-1BIO_METHOD\s0\fR structure. It should be given a
 196 unique integer \fBtype\fR and a string that represents its \fBname\fR.
 197 Use \fBBIO_get_new_index()\fR to get the value for \fBtype\fR.
 198 .PP
 199 The set of
 200 standard OpenSSL provided \s-1BIO\s0 types is provided in \fBbio.h\fR. Some examples
 201 include \fB\s-1BIO_TYPE_BUFFER\s0\fR and \fB\s-1BIO_TYPE_CIPHER\s0\fR. Filter BIOs should have a
 202 type which have the \*(L"filter\*(R" bit set (\fB\s-1BIO_TYPE_FILTER\s0\fR). Source/sink BIOs
 203 should have the \*(L"source/sink\*(R" bit set (\fB\s-1BIO_TYPE_SOURCE_SINK\s0\fR). File descriptor
 204 based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the
 205 \&\*(L"descriptor\*(R" bit set (\fB\s-1BIO_TYPE_DESCRIPTOR\s0\fR). See the BIO_find_type page for
 206 more information.
 207 .PP
 208 \&\fBBIO_meth_free()\fR destroys a \fB\s-1BIO_METHOD\s0\fR structure and frees up any memory
 209 associated with it.
 210 .PP
 211 \&\fBBIO_meth_get_write_ex()\fR and \fBBIO_meth_set_write_ex()\fR get and set the function
 212 used for writing arbitrary length data to the \s-1BIO\s0 respectively. This function
 213 will be called in response to the application calling \fBBIO_write_ex()\fR or
 214 \&\fBBIO_write()\fR. The parameters for the function have the same meaning as for
 215 \&\fBBIO_write_ex()\fR. Older code may call \fBBIO_meth_get_write()\fR and
 216 \&\fBBIO_meth_set_write()\fR instead. Applications should not call both
 217 \&\fBBIO_meth_set_write_ex()\fR and \fBBIO_meth_set_write()\fR or call \fBBIO_meth_get_write()\fR
 218 when the function was set with \fBBIO_meth_set_write_ex()\fR.
 219 .PP
 220 \&\fBBIO_meth_get_read_ex()\fR and \fBBIO_meth_set_read_ex()\fR get and set the function used
 221 for reading arbitrary length data from the \s-1BIO\s0 respectively. This function will
 222 be called in response to the application calling \fBBIO_read_ex()\fR or \fBBIO_read()\fR.
 223 The parameters for the function have the same meaning as for \fBBIO_read_ex()\fR.
 224 Older code may call \fBBIO_meth_get_read()\fR and \fBBIO_meth_set_read()\fR instead.
 225 Applications should not call both \fBBIO_meth_set_read_ex()\fR and \fBBIO_meth_set_read()\fR
 226 or call \fBBIO_meth_get_read()\fR when the function was set with
 227 \&\fBBIO_meth_set_read_ex()\fR.
 228 .PP
 229 \&\fBBIO_meth_get_puts()\fR and \fBBIO_meth_set_puts()\fR get and set the function used for
 230 writing a \s-1NULL\s0 terminated string to the \s-1BIO\s0 respectively. This function will be
 231 called in response to the application calling \fBBIO_puts()\fR. The parameters for
 232 the function have the same meaning as for \fBBIO_puts()\fR.
 233 .PP
 234 \&\fBBIO_meth_get_gets()\fR and \fBBIO_meth_set_gets()\fR get and set the function typically
 235 used for reading a line of data from the \s-1BIO\s0 respectively (see the \fBBIO_gets\fR\|(3)
 236 page for more information). This function will be called in response to the
 237 application calling \fBBIO_gets()\fR. The parameters for the function have the same
 238 meaning as for \fBBIO_gets()\fR.
 239 .PP
 240 \&\fBBIO_meth_get_ctrl()\fR and \fBBIO_meth_set_ctrl()\fR get and set the function used for
 241 processing ctrl messages in the \s-1BIO\s0 respectively. See the BIO_ctrl page for
 242 more information. This function will be called in response to the application
 243 calling \fBBIO_ctrl()\fR. The parameters for the function have the same meaning as for
 244 \&\fBBIO_ctrl()\fR.
 245 .PP
 246 \&\fBBIO_meth_get_create()\fR and \fBBIO_meth_set_create()\fR get and set the function used
 247 for creating a new instance of the \s-1BIO\s0 respectively. This function will be
 248 called in response to the application calling \fBBIO_new()\fR and passing
 249 in a pointer to the current \s-1BIO_METHOD.\s0 The \fBBIO_new()\fR function will allocate the
 250 memory for the new \s-1BIO,\s0 and a pointer to this newly allocated structure will
 251 be passed as a parameter to the function.
 252 .PP
 253 \&\fBBIO_meth_get_destroy()\fR and \fBBIO_meth_set_destroy()\fR get and set the function used
 254 for destroying an instance of a \s-1BIO\s0 respectively. This function will be
 255 called in response to the application calling \fBBIO_free()\fR. A pointer to the \s-1BIO\s0
 256 to be destroyed is passed as a parameter. The destroy function should be used
 257 for \s-1BIO\s0 specific clean up. The memory for the \s-1BIO\s0 itself should not be freed by
 258 this function.
 259 .PP
 260 \&\fBBIO_meth_get_callback_ctrl()\fR and \fBBIO_meth_set_callback_ctrl()\fR get and set the
 261 function used for processing callback ctrl messages in the \s-1BIO\s0 respectively. See
 262 the \fBBIO_callback_ctrl\fR\|(3) page for more information. This function will be called
 263 in response to the application calling \fBBIO_callback_ctrl()\fR. The parameters for
 264 the function have the same meaning as for \fBBIO_callback_ctrl()\fR.
 265 .SH "RETURN VALUES"
 266 .IX Header "RETURN VALUES"
 267 \&\fBBIO_get_new_index()\fR returns the new \s-1BIO\s0 type value or \-1 if an error occurred.
 268 .PP
 269 BIO_meth_new(int type, const char *name) returns a valid \fB\s-1BIO_METHOD\s0\fR or \s-1NULL\s0
 270 if an error occurred.
 271 .PP
 272 The \fBBIO_meth_set\fR functions return 1 on success or 0 on error.
 273 .PP
 274 The \fBBIO_meth_get\fR functions return the corresponding function pointers.
 275 .SH "SEE ALSO"
 276 .IX Header "SEE ALSO"
 277 bio, BIO_find_type, BIO_ctrl, BIO_read_ex, BIO_new
 278 .SH "HISTORY"
 279 .IX Header "HISTORY"
 280 The functions described here were added in OpenSSL 1.1.0.
 281 .SH "COPYRIGHT"
 282 .IX Header "COPYRIGHT"
 283 Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved.
 284 .PP
 285 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 286 this file except in compliance with the License.  You can obtain a copy
 287 in the file \s-1LICENSE\s0 in the source distribution or at
 288 <https://www.openssl.org/source/license.html>.