• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 - 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
61The B<BIO_METHOD> type is a structure used for the implementation of new BIO
62types. It provides a set of functions used by OpenSSL for the implementation
63of the various BIO capabilities. See the L<bio> page for more information.
64
65BIO_meth_new() creates a new B<BIO_METHOD> structure. It should be given a
66unique integer B<type> and a string that represents its B<name>.
67Use BIO_get_new_index() to get the value for B<type>.
68
69The set of
70standard OpenSSL provided BIO types is provided in B<bio.h>. Some examples
71include B<BIO_TYPE_BUFFER> and B<BIO_TYPE_CIPHER>. Filter BIOs should have a
72type which have the "filter" bit set (B<BIO_TYPE_FILTER>). Source/sink BIOs
73should have the "source/sink" bit set (B<BIO_TYPE_SOURCE_SINK>). File descriptor
74based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the
75"descriptor" bit set (B<BIO_TYPE_DESCRIPTOR>). See the L<BIO_find_type> page for
76more information.
77
78BIO_meth_free() destroys a B<BIO_METHOD> structure and frees up any memory
79associated with it.
80
81BIO_meth_get_write_ex() and BIO_meth_set_write_ex() get and set the function
82used for writing arbitrary length data to the BIO respectively. This function
83will be called in response to the application calling BIO_write_ex() or
84BIO_write(). The parameters for the function have the same meaning as for
85BIO_write_ex(). Older code may call BIO_meth_get_write() and
86BIO_meth_set_write() instead. Applications should not call both
87BIO_meth_set_write_ex() and BIO_meth_set_write() or call BIO_meth_get_write()
88when the function was set with BIO_meth_set_write_ex().
89
90BIO_meth_get_read_ex() and BIO_meth_set_read_ex() get and set the function used
91for reading arbitrary length data from the BIO respectively. This function will
92be called in response to the application calling BIO_read_ex() or BIO_read().
93The parameters for the function have the same meaning as for BIO_read_ex().
94Older code may call BIO_meth_get_read() and BIO_meth_set_read() instead.
95Applications should not call both BIO_meth_set_read_ex() and BIO_meth_set_read()
96or call BIO_meth_get_read() when the function was set with
97BIO_meth_set_read_ex().
98
99BIO_meth_get_puts() and BIO_meth_set_puts() get and set the function used for
100writing a NULL terminated string to the BIO respectively. This function will be
101called in response to the application calling BIO_puts(). The parameters for
102the function have the same meaning as for BIO_puts().
103
104BIO_meth_get_gets() and BIO_meth_set_gets() get and set the function typically
105used for reading a line of data from the BIO respectively (see the L<BIO_gets(3)>
106page for more information). This function will be called in response to the
107application calling BIO_gets(). The parameters for the function have the same
108meaning as for BIO_gets().
109
110BIO_meth_get_ctrl() and BIO_meth_set_ctrl() get and set the function used for
111processing ctrl messages in the BIO respectively. See the L<BIO_ctrl> page for
112more information. This function will be called in response to the application
113calling BIO_ctrl(). The parameters for the function have the same meaning as for
114BIO_ctrl().
115
116BIO_meth_get_create() and BIO_meth_set_create() get and set the function used
117for creating a new instance of the BIO respectively. This function will be
118called in response to the application calling BIO_new() and passing
119in a pointer to the current BIO_METHOD. The BIO_new() function will allocate the
120memory for the new BIO, and a pointer to this newly allocated structure will
121be passed as a parameter to the function.
122
123BIO_meth_get_destroy() and BIO_meth_set_destroy() get and set the function used
124for destroying an instance of a BIO respectively. This function will be
125called in response to the application calling BIO_free(). A pointer to the BIO
126to be destroyed is passed as a parameter. The destroy function should be used
127for BIO specific clean up. The memory for the BIO itself should not be freed by
128this function.
129
130BIO_meth_get_callback_ctrl() and BIO_meth_set_callback_ctrl() get and set the
131function used for processing callback ctrl messages in the BIO respectively. See
132the L<BIO_callback_ctrl(3)> page for more information. This function will be called
133in response to the application calling BIO_callback_ctrl(). The parameters for
134the function have the same meaning as for BIO_callback_ctrl().
135
136=head1 RETURN VALUES
137
138BIO_get_new_index() returns the new BIO type value or -1 if an error occurred.
139
140BIO_meth_new(int type, const char *name) returns a valid B<BIO_METHOD> or NULL
141if an error occurred.
142
143The B<BIO_meth_set> functions return 1 on success or 0 on error.
144
145The B<BIO_meth_get> functions return the corresponding function pointers.
146
147=head1 SEE ALSO
148
149L<bio>, L<BIO_find_type>, L<BIO_ctrl>, L<BIO_read_ex>, L<BIO_new>
150
151=head1 HISTORY
152
153The functions described here were added in OpenSSL 1.1.0.
154
155=head1 COPYRIGHT
156
157Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
158
159Licensed under the OpenSSL license (the "License").  You may not use
160this file except in compliance with the License.  You can obtain a copy
161in the file LICENSE in the source distribution or at
162L<https://www.openssl.org/source/license.html>.
163
164=cut
165