xref: /openssl/doc/man3/BIO_meth_new.pod (revision 981d129a) 
1=pod
2
3=head1 NAME
4
5BIO_get_new_index,
6BIO_meth_new, BIO_meth_free, BIO_meth_get_read_ex, BIO_meth_set_read_ex,
7BIO_meth_get_write_ex, BIO_meth_set_write_ex, BIO_meth_get_write,
8BIO_meth_set_write, BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts,
9BIO_meth_set_puts, BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl,
10BIO_meth_set_ctrl, BIO_meth_get_create, BIO_meth_set_create,
11BIO_meth_get_destroy, BIO_meth_set_destroy, BIO_meth_get_callback_ctrl,
12BIO_meth_set_callback_ctrl, BIO_meth_set_sendmmsg, BIO_meth_get_sendmmsg,
13BIO_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
81The B<BIO_METHOD> type is a structure used for the implementation of new BIO
82types. It provides a set of functions used by OpenSSL for the implementation
83of the various BIO capabilities. See the L<bio(7)> page for more information.
84
85BIO_meth_new() creates a new B<BIO_METHOD> structure that contains a type
86identifier I<type> and a string that represents its B<name>.
87B<type> can be set to either B<BIO_TYPE_NONE> or via BIO_get_new_index() if
88a unique type is required for searching (See L<BIO_find_type(3)>)
89
90Note that BIO_get_new_index() can only be used 127 times before it returns an
91error.
92
93The set of
94standard OpenSSL provided BIO types is provided in F<< <openssl/bio.h> >>.
95Some examples include B<BIO_TYPE_BUFFER> and B<BIO_TYPE_CIPHER>. Filter BIOs
96should have a type which have the "filter" bit set (B<BIO_TYPE_FILTER>).
97Source/sink BIOs should have the "source/sink" bit set (B<BIO_TYPE_SOURCE_SINK>).
98File descriptor based BIOs (e.g. socket, fd, connect, accept etc) should
99additionally have the "descriptor" bit set (B<BIO_TYPE_DESCRIPTOR>). See the
100L<BIO_find_type(3)> page for more information.
101
102BIO_meth_free() destroys a B<BIO_METHOD> structure and frees up any memory
103associated with it. If the argument is NULL, nothing is done.
104
105BIO_meth_get_write_ex() and BIO_meth_set_write_ex() get and set the function
106used for writing arbitrary length data to the BIO respectively. This function
107will be called in response to the application calling BIO_write_ex() or
108BIO_write(). The parameters for the function have the same meaning as for
109BIO_write_ex(). Older code may call BIO_meth_get_write() and
110BIO_meth_set_write() instead. Applications should not call both
111BIO_meth_set_write_ex() and BIO_meth_set_write() or call BIO_meth_get_write()
112when the function was set with BIO_meth_set_write_ex().
113
114BIO_meth_get_read_ex() and BIO_meth_set_read_ex() get and set the function used
115for reading arbitrary length data from the BIO respectively. This function will
116be called in response to the application calling BIO_read_ex() or BIO_read().
117The parameters for the function have the same meaning as for BIO_read_ex().
118Older code may call BIO_meth_get_read() and BIO_meth_set_read() instead.
119Applications should not call both BIO_meth_set_read_ex() and BIO_meth_set_read()
120or call BIO_meth_get_read() when the function was set with
121BIO_meth_set_read_ex().
122
123BIO_meth_get_puts() and BIO_meth_set_puts() get and set the function used for
124writing a NULL terminated string to the BIO respectively. This function will be
125called in response to the application calling BIO_puts(). The parameters for
126the function have the same meaning as for BIO_puts().
127
128BIO_meth_get_gets() and BIO_meth_set_gets() get and set the function typically
129used for reading a line of data from the BIO respectively (see the L<BIO_gets(3)>
130page for more information). This function will be called in response to the
131application calling BIO_gets(). The parameters for the function have the same
132meaning as for BIO_gets().
133
134BIO_meth_get_ctrl() and BIO_meth_set_ctrl() get and set the function used for
135processing ctrl messages in the BIO respectively. See the L<BIO_ctrl(3)> page for
136more information. This function will be called in response to the application
137calling BIO_ctrl(). The parameters for the function have the same meaning as for
138BIO_ctrl().
139
140BIO_meth_get_create() and BIO_meth_set_create() get and set the function used
141for creating a new instance of the BIO respectively. This function will be
142called in response to the application calling BIO_new() and passing
143in a pointer to the current BIO_METHOD. The BIO_new() function will allocate the
144memory for the new BIO, and a pointer to this newly allocated structure will
145be passed as a parameter to the function. If a create function is set,
146BIO_new() will not mark the BIO as initialised on allocation.
147L<BIO_set_init(3)> must then be called either by the create function, or later,
148by a BIO ctrl function, once BIO initialisation is complete.
149
150BIO_meth_get_destroy() and BIO_meth_set_destroy() get and set the function used
151for destroying an instance of a BIO respectively. This function will be
152called in response to the application calling BIO_free(). A pointer to the BIO
153to be destroyed is passed as a parameter. The destroy function should be used
154for BIO specific clean up. The memory for the BIO itself should not be freed by
155this function.
156
157BIO_meth_get_callback_ctrl() and BIO_meth_set_callback_ctrl() get and set the
158function used for processing callback ctrl messages in the BIO respectively. See
159the L<BIO_callback_ctrl(3)> page for more information. This function will be called
160in response to the application calling BIO_callback_ctrl(). The parameters for
161the function have the same meaning as for BIO_callback_ctrl().
162
163BIO_meth_get_sendmmsg(), BIO_meth_set_sendmmsg(), BIO_meth_get_recvmmsg() and
164BIO_meth_set_recvmmsg() get and set the functions used for handling
165BIO_sendmmsg() and BIO_recvmmsg() calls respectively. See L<BIO_sendmmsg(3)> for
166more information.
167
168=head1 RETURN VALUES
169
170BIO_get_new_index() returns the new BIO type value or -1 if an error occurred.
171
172BIO_meth_new(int type, const char *name) returns a valid B<BIO_METHOD> or NULL
173if an error occurred.
174
175The B<BIO_meth_set> functions return 1 on success or 0 on error.
176
177The B<BIO_meth_get> functions return the corresponding function pointers.
178
179=head1 SEE ALSO
180
181L<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
185The functions described here were added in OpenSSL 1.1.0.
186
187=head1 COPYRIGHT
188
189Copyright 2016-2024 The OpenSSL Project Authors. All Rights Reserved.
190
191Licensed under the Apache License 2.0 (the "License").  You may not use
192this file except in compliance with the License.  You can obtain a copy
193in the file LICENSE in the source distribution or at
194L<https://www.openssl.org/source/license.html>.
195
196=cut
197