]>
Commit | Line | Data |
---|---|---|
85556b4d MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
8b8d963d | 5 | BIO_get_new_index, |
b055fceb MC |
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, | |
2bcb232e | 12 | BIO_meth_set_callback_ctrl - Routines to build up BIO methods |
85556b4d MC |
13 | |
14 | =head1 SYNOPSIS | |
15 | ||
16 | #include <openssl/bio.h> | |
17 | ||
8b8d963d | 18 | int BIO_get_new_index(void); |
e9b77246 | 19 | |
85556b4d | 20 | BIO_METHOD *BIO_meth_new(int type, const char *name); |
e9b77246 | 21 | |
85556b4d | 22 | void BIO_meth_free(BIO_METHOD *biom); |
e9b77246 | 23 | |
693be9a2 | 24 | int (*BIO_meth_get_write_ex(const BIO_METHOD *biom))(BIO *, const char *, size_t, |
e9b77246 | 25 | size_t *); |
693be9a2 | 26 | int (*BIO_meth_get_write(const BIO_METHOD *biom))(BIO *, const char *, int); |
b055fceb | 27 | int BIO_meth_set_write_ex(BIO_METHOD *biom, |
e9b77246 | 28 | int (*bwrite)(BIO *, const char *, size_t, size_t *)); |
85556b4d | 29 | int BIO_meth_set_write(BIO_METHOD *biom, |
e9b77246 BB |
30 | int (*write)(BIO *, const char *, int)); |
31 | ||
693be9a2 JB |
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); | |
b055fceb | 34 | int BIO_meth_set_read_ex(BIO_METHOD *biom, |
e9b77246 BB |
35 | int (*bread)(BIO *, char *, size_t, size_t *)); |
36 | int BIO_meth_set_read(BIO_METHOD *biom, int (*read)(BIO *, char *, int)); | |
37 | ||
693be9a2 | 38 | int (*BIO_meth_get_puts(const BIO_METHOD *biom))(BIO *, const char *); |
e9b77246 BB |
39 | int BIO_meth_set_puts(BIO_METHOD *biom, int (*puts)(BIO *, const char *)); |
40 | ||
693be9a2 | 41 | int (*BIO_meth_get_gets(const BIO_METHOD *biom))(BIO *, char *, int); |
85556b4d | 42 | int BIO_meth_set_gets(BIO_METHOD *biom, |
e9b77246 BB |
43 | int (*gets)(BIO *, char *, int)); |
44 | ||
693be9a2 | 45 | long (*BIO_meth_get_ctrl(const BIO_METHOD *biom))(BIO *, int, long, void *); |
85556b4d | 46 | int BIO_meth_set_ctrl(BIO_METHOD *biom, |
e9b77246 BB |
47 | long (*ctrl)(BIO *, int, long, void *)); |
48 | ||
693be9a2 | 49 | int (*BIO_meth_get_create(const BIO_METHOD *bion))(BIO *); |
e9b77246 BB |
50 | int BIO_meth_set_create(BIO_METHOD *biom, int (*create)(BIO *)); |
51 | ||
693be9a2 | 52 | int (*BIO_meth_get_destroy(const BIO_METHOD *biom))(BIO *); |
e9b77246 BB |
53 | int BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy)(BIO *)); |
54 | ||
693be9a2 | 55 | long (*BIO_meth_get_callback_ctrl(const BIO_METHOD *biom))(BIO *, int, BIO_info_cb *); |
85556b4d | 56 | int BIO_meth_set_callback_ctrl(BIO_METHOD *biom, |
fce78bd4 | 57 | long (*callback_ctrl)(BIO *, int, BIO_info_cb *)); |
85556b4d MC |
58 | |
59 | =head1 DESCRIPTION | |
60 | ||
61 | The B<BIO_METHOD> type is a structure used for the implementation of new BIO | |
a970b14f | 62 | types. It provides a set of functions used by OpenSSL for the implementation |
6e4618a0 | 63 | of the various BIO capabilities. See the L<bio(7)> page for more information. |
85556b4d MC |
64 | |
65 | BIO_meth_new() creates a new B<BIO_METHOD> structure. It should be given a | |
8b8d963d RS |
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 | |
85556b4d MC |
70 | standard OpenSSL provided BIO types is provided in B<bio.h>. Some examples |
71 | include B<BIO_TYPE_BUFFER> and B<BIO_TYPE_CIPHER>. Filter BIOs should have a | |
72 | type which have the "filter" bit set (B<BIO_TYPE_FILTER>). Source/sink BIOs | |
73 | should have the "source/sink" bit set (B<BIO_TYPE_SOURCE_SINK>). File descriptor | |
74 | based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the | |
6e4618a0 | 75 | "descriptor" bit set (B<BIO_TYPE_DESCRIPTOR>). See the L<BIO_find_type(3)> page for |
85556b4d MC |
76 | more information. |
77 | ||
78 | BIO_meth_free() destroys a B<BIO_METHOD> structure and frees up any memory | |
79 | associated with it. | |
80 | ||
b055fceb MC |
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(). | |
85556b4d MC |
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 | |
ecba1fb3 | 105 | used for reading a line of data from the BIO respectively (see the L<BIO_gets(3)> |
85556b4d MC |
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 | |
6e4618a0 | 111 | processing ctrl messages in the BIO respectively. See the L<BIO_ctrl(3)> page for |
85556b4d MC |
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 | |
9d7bfb14 | 118 | called in response to the application calling BIO_new() and passing |
85556b4d MC |
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. | |
122 | ||
123 | BIO_meth_get_destroy() and BIO_meth_set_destroy() get and set the function used | |
124 | for destroying an instance of a BIO respectively. This function will be | |
125 | called in response to the application calling BIO_free(). A pointer to the BIO | |
126 | to be destroyed is passed as a parameter. The destroy function should be used | |
127 | for BIO specific clean up. The memory for the BIO itself should not be freed by | |
128 | this function. | |
129 | ||
130 | BIO_meth_get_callback_ctrl() and BIO_meth_set_callback_ctrl() get and set the | |
131 | function used for processing callback ctrl messages in the BIO respectively. See | |
ecba1fb3 | 132 | the L<BIO_callback_ctrl(3)> page for more information. This function will be called |
85556b4d MC |
133 | in response to the application calling BIO_callback_ctrl(). The parameters for |
134 | the function have the same meaning as for BIO_callback_ctrl(). | |
135 | ||
1f13ad31 PY |
136 | =head1 RETURN VALUES |
137 | ||
138 | BIO_get_new_index() returns the new BIO type value or -1 if an error occurred. | |
139 | ||
140 | BIO_meth_new(int type, const char *name) returns a valid B<BIO_METHOD> or NULL | |
141 | if an error occurred. | |
142 | ||
143 | The B<BIO_meth_set> functions return 1 on success or 0 on error. | |
144 | ||
145 | The B<BIO_meth_get> functions return the corresponding function pointers. | |
146 | ||
85556b4d MC |
147 | =head1 SEE ALSO |
148 | ||
6e4618a0 | 149 | L<bio(7)>, L<BIO_find_type(3)>, L<BIO_ctrl(3)>, L<BIO_read_ex(3)>, L<BIO_new(3)> |
85556b4d MC |
150 | |
151 | =head1 HISTORY | |
152 | ||
e90fc053 | 153 | The functions described here were added in OpenSSL 1.1.0. |
85556b4d | 154 | |
e2f92610 RS |
155 | =head1 COPYRIGHT |
156 | ||
61f805c1 | 157 | Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 158 | |
4746f25a | 159 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
160 | this file except in compliance with the License. You can obtain a copy |
161 | in the file LICENSE in the source distribution or at | |
162 | L<https://www.openssl.org/source/license.html>. | |
163 | ||
164 | =cut |