doc/man3/BIO_meth_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 BIO_get_new_index,
   6 BIO_meth_new, BIO_meth_free, BIO_meth_get_read_ex, BIO_meth_set_read_ex,
   7 BIO_meth_get_write_ex, BIO_meth_set_write_ex, BIO_meth_get_write,
   8 BIO_meth_set_write, BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts,
   9 BIO_meth_set_puts, BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl,
  10 BIO_meth_set_ctrl, BIO_meth_get_create, BIO_meth_set_create,
  11 BIO_meth_get_destroy, BIO_meth_set_destroy, BIO_meth_get_callback_ctrl,
  12 BIO_meth_set_callback_ctrl, BIO_meth_set_sendmmsg, BIO_meth_get_sendmmsg,
  13 BIO_meth_set_recvmmsg, BIO_meth_get_recvmmsg - Routines to build up BIO methods
  14
  15 =head1 SYNOPSIS
  16
  17  #include <openssl/bio.h>
  18
  19  int BIO_get_new_index(void);
  20
  21  BIO_METHOD *BIO_meth_new(int type, const char *name);
  22
  23  void BIO_meth_free(BIO_METHOD *biom);
  24
  25  int (*BIO_meth_get_write_ex(const BIO_METHOD *biom))(BIO *, const char *, size_t,
  26                                                 size_t *);
  27  int (*BIO_meth_get_write(const BIO_METHOD *biom))(BIO *, const char *, int);
  28  int BIO_meth_set_write_ex(BIO_METHOD *biom,
  29                            int (*bwrite)(BIO *, const char *, size_t, size_t *));
  30  int BIO_meth_set_write(BIO_METHOD *biom,
  31                         int (*write)(BIO *, const char *, int));
  32
  33  int (*BIO_meth_get_read_ex(const BIO_METHOD *biom))(BIO *, char *, size_t, size_t *);
  34  int (*BIO_meth_get_read(const BIO_METHOD *biom))(BIO *, char *, int);
  35  int BIO_meth_set_read_ex(BIO_METHOD *biom,
  36                           int (*bread)(BIO *, char *, size_t, size_t *));
  37  int BIO_meth_set_read(BIO_METHOD *biom, int (*read)(BIO *, char *, int));
  38
  39  int (*BIO_meth_get_puts(const BIO_METHOD *biom))(BIO *, const char *);
  40  int BIO_meth_set_puts(BIO_METHOD *biom, int (*puts)(BIO *, const char *));
  41
  42  int (*BIO_meth_get_gets(const BIO_METHOD *biom))(BIO *, char *, int);
  43  int BIO_meth_set_gets(BIO_METHOD *biom,
  44                        int (*gets)(BIO *, char *, int));
  45
  46  long (*BIO_meth_get_ctrl(const BIO_METHOD *biom))(BIO *, int, long, void *);
  47  int BIO_meth_set_ctrl(BIO_METHOD *biom,
  48                        long (*ctrl)(BIO *, int, long, void *));
  49
  50  int (*BIO_meth_get_create(const BIO_METHOD *bion))(BIO *);
  51  int BIO_meth_set_create(BIO_METHOD *biom, int (*create)(BIO *));
  52
  53  int (*BIO_meth_get_destroy(const BIO_METHOD *biom))(BIO *);
  54  int BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy)(BIO *));
  55
  56  long (*BIO_meth_get_callback_ctrl(const BIO_METHOD *biom))(BIO *, int, BIO_info_cb *);
  57  int BIO_meth_set_callback_ctrl(BIO_METHOD *biom,
  58                                 long (*callback_ctrl)(BIO *, int, BIO_info_cb *));
  59
  60  ossl_ssize_t (*BIO_meth_get_sendmmsg(const BIO_METHOD *biom))(BIO *,
  61                                                                BIO_MSG *,
  62                                                                size_t,
  63                                                                size_t,
  64                                                                uint64_t);
  65  int BIO_meth_set_sendmmsg(BIO_METHOD *biom,
  66                            ossl_ssize_t (*f) (BIO *, BIO_MSG *, size_t,
  67                                               size_t, uint64_t));
  68
  69  ossl_ssize_t (*BIO_meth_get_recvmmsg(const BIO_METHOD *biom))(BIO *,
  70                                                                BIO_MSG *,
  71                                                                size_t,
  72                                                                size_t,
  73                                                                uint64_t);
  74  int BIO_meth_set_recvmmsg(BIO_METHOD *biom,
  75                            ossl_ssize_t (*f) (BIO *, BIO_MSG *, size_t,
  76                                               size_t, uint64_t));
  77
  78
  79 =head1 DESCRIPTION
  80
  81 The B<BIO_METHOD> type is a structure used for the implementation of new BIO
  82 types. It provides a set of functions used by OpenSSL for the implementation
  83 of the various BIO capabilities. See the L<bio(7)> page for more information.
  84
  85 BIO_meth_new() creates a new B<BIO_METHOD> structure that contains a type
  86 identifier I<type> and a string that represents its B<name>.
  87 B<type> can be set to either B<BIO_TYPE_NONE> or via BIO_get_new_index() if
  88 a unique type is required for searching (See L<BIO_find_type(3)>)
  89
  90 Note that BIO_get_new_index() can only be used 127 times before it returns an
  91 error.
  92
  93 The set of
  94 standard OpenSSL provided BIO types is provided in F<< <openssl/bio.h> >>.
  95 Some examples include B<BIO_TYPE_BUFFER> and B<BIO_TYPE_CIPHER>. Filter BIOs
  96 should have a type which have the "filter" bit set (B<BIO_TYPE_FILTER>).
  97 Source/sink BIOs should have the "source/sink" bit set (B<BIO_TYPE_SOURCE_SINK>).
  98 File descriptor based BIOs (e.g. socket, fd, connect, accept etc) should
  99 additionally have the "descriptor" bit set (B<BIO_TYPE_DESCRIPTOR>). See the
 100 L<BIO_find_type(3)> page for more information.
 101
 102 BIO_meth_free() destroys a B<BIO_METHOD> structure and frees up any memory
 103 associated with it.
 104
 105 BIO_meth_get_write_ex() and BIO_meth_set_write_ex() get and set the function
 106 used for writing arbitrary length data to the BIO respectively. This function
 107 will be called in response to the application calling BIO_write_ex() or
 108 BIO_write(). The parameters for the function have the same meaning as for
 109 BIO_write_ex(). Older code may call BIO_meth_get_write() and
 110 BIO_meth_set_write() instead. Applications should not call both
 111 BIO_meth_set_write_ex() and BIO_meth_set_write() or call BIO_meth_get_write()
 112 when the function was set with BIO_meth_set_write_ex().
 113
 114 BIO_meth_get_read_ex() and BIO_meth_set_read_ex() get and set the function used
 115 for reading arbitrary length data from the BIO respectively. This function will
 116 be called in response to the application calling BIO_read_ex() or BIO_read().
 117 The parameters for the function have the same meaning as for BIO_read_ex().
 118 Older code may call BIO_meth_get_read() and BIO_meth_set_read() instead.
 119 Applications should not call both BIO_meth_set_read_ex() and BIO_meth_set_read()
 120 or call BIO_meth_get_read() when the function was set with
 121 BIO_meth_set_read_ex().
 122
 123 BIO_meth_get_puts() and BIO_meth_set_puts() get and set the function used for
 124 writing a NULL terminated string to the BIO respectively. This function will be
 125 called in response to the application calling BIO_puts(). The parameters for
 126 the function have the same meaning as for BIO_puts().
 127
 128 BIO_meth_get_gets() and BIO_meth_set_gets() get and set the function typically
 129 used for reading a line of data from the BIO respectively (see the L<BIO_gets(3)>
 130 page for more information). This function will be called in response to the
 131 application calling BIO_gets(). The parameters for the function have the same
 132 meaning as for BIO_gets().
 133
 134 BIO_meth_get_ctrl() and BIO_meth_set_ctrl() get and set the function used for
 135 processing ctrl messages in the BIO respectively. See the L<BIO_ctrl(3)> page for
 136 more information. This function will be called in response to the application
 137 calling BIO_ctrl(). The parameters for the function have the same meaning as for
 138 BIO_ctrl().
 139
 140 BIO_meth_get_create() and BIO_meth_set_create() get and set the function used
 141 for creating a new instance of the BIO respectively. This function will be
 142 called in response to the application calling BIO_new() and passing
 143 in a pointer to the current BIO_METHOD. The BIO_new() function will allocate the
 144 memory for the new BIO, and a pointer to this newly allocated structure will
 145 be passed as a parameter to the function. If a create function is set,
 146 BIO_new() will not mark the BIO as initialised on allocation.
 147 L<BIO_set_init(3)> must then be called either by the create function, or later,
 148 by a BIO ctrl function, once BIO initialisation is complete.
 149
 150 BIO_meth_get_destroy() and BIO_meth_set_destroy() get and set the function used
 151 for destroying an instance of a BIO respectively. This function will be
 152 called in response to the application calling BIO_free(). A pointer to the BIO
 153 to be destroyed is passed as a parameter. The destroy function should be used
 154 for BIO specific clean up. The memory for the BIO itself should not be freed by
 155 this function.
 156
 157 BIO_meth_get_callback_ctrl() and BIO_meth_set_callback_ctrl() get and set the
 158 function used for processing callback ctrl messages in the BIO respectively. See
 159 the L<BIO_callback_ctrl(3)> page for more information. This function will be called
 160 in response to the application calling BIO_callback_ctrl(). The parameters for
 161 the function have the same meaning as for BIO_callback_ctrl().
 162
 163 BIO_meth_get_sendmmsg(), BIO_meth_set_sendmmsg(), BIO_meth_get_recvmmsg() and
 164 BIO_meth_set_recvmmsg() get and set the functions used for handling
 165 BIO_sendmmsg() and BIO_recvmmsg() calls respectively. See L<BIO_sendmmsg(3)> for
 166 more information.
 167
 168 =head1 RETURN VALUES
 169
 170 BIO_get_new_index() returns the new BIO type value or -1 if an error occurred.
 171
 172 BIO_meth_new(int type, const char *name) returns a valid B<BIO_METHOD> or NULL
 173 if an error occurred.
 174
 175 The B<BIO_meth_set> functions return 1 on success or 0 on error.
 176
 177 The B<BIO_meth_get> functions return the corresponding function pointers.
 178
 179 =head1 SEE ALSO
 180
 181 L<bio(7)>, L<BIO_find_type(3)>, L<BIO_ctrl(3)>, L<BIO_read_ex(3)>, L<BIO_new(3)>
 182
 183 =head1 HISTORY
 184
 185 The functions described here were added in OpenSSL 1.1.0.
 186
 187 =head1 COPYRIGHT
 188
 189 Copyright 2016-2024 The OpenSSL Project Authors. All Rights Reserved.
 190
 191 Licensed under the Apache License 2.0 (the "License").  You may not use
 192 this file except in compliance with the License.  You can obtain a copy
 193 in the file LICENSE in the source distribution or at
 194 L<https://www.openssl.org/source/license.html>.
 195
 196 =cut