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