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