]>
Commit | Line | Data |
---|---|---|
47770c4d DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
53934822 | 5 | bio - Basic I/O abstraction |
47770c4d DSH |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
a9c85cea RL |
9 | =for comment generic |
10 | ||
47770c4d DSH |
11 | #include <openssl/bio.h> |
12 | ||
47770c4d DSH |
13 | =head1 DESCRIPTION |
14 | ||
15 | A BIO is an I/O abstraction, it hides many of the underlying I/O | |
16 | details from an application. If an application uses a BIO for its | |
17 | I/O it can transparently handle SSL connections, unencrypted network | |
18 | connections and file I/O. | |
19 | ||
20 | There are two type of BIO, a source/sink BIO and a filter BIO. | |
21 | ||
1974a58f | 22 | As its name implies a source/sink BIO is a source and/or sink of data, |
47770c4d DSH |
23 | examples include a socket BIO and a file BIO. |
24 | ||
25 | A filter BIO takes data from one BIO and passes it through to | |
26 | another, or the application. The data may be left unmodified (for | |
27 | example a message digest BIO) or translated (for example an | |
28 | encryption BIO). The effect of a filter BIO may change according | |
29 | to the I/O operation it is performing: for example an encryption | |
30 | BIO will encrypt data if it is being written to and decrypt data | |
31 | if it is being read from. | |
32 | ||
33 | BIOs can be joined together to form a chain (a single BIO is a chain | |
34 | with one component). A chain normally consist of one source/sink | |
35 | BIO and one or more filter BIOs. Data read from or written to the | |
5fd0cd9a | 36 | first BIO then traverses the chain to the end (normally a source/sink |
47770c4d DSH |
37 | BIO). |
38 | ||
53934822 RS |
39 | |
40 | Some BIOs (such as memory BIOs) can be used immediately after calling | |
41 | BIO_new(). Others (such as file BIOs) need some additional initialization, | |
42 | and frequently a utility function exists to create and initialize such BIOs. | |
43 | ||
44 | If BIO_free() is called on a BIO chain it will only free one BIO resulting | |
45 | in a memory leak. | |
46 | ||
631c37be DB |
47 | Calling BIO_free_all() on a single BIO has the same effect as calling |
48 | BIO_free() on it other than the discarded return value. | |
53934822 | 49 | |
dfabee82 | 50 | Normally the I<type> argument is supplied by a function which returns a |
53934822 | 51 | pointer to a BIO_METHOD. There is a naming convention for such functions: |
c18d2d94 RL |
52 | a source/sink BIO is normally called B<BIO_s_I<*>>() and a filter BIO |
53 | B<BIO_f_I<*>>(); | |
53934822 | 54 | |
cda77422 | 55 | =head1 EXAMPLES |
53934822 RS |
56 | |
57 | Create a memory BIO: | |
58 | ||
59 | BIO *mem = BIO_new(BIO_s_mem()); | |
60 | ||
47770c4d DSH |
61 | =head1 SEE ALSO |
62 | ||
9b86974e RS |
63 | L<BIO_ctrl(3)>, |
64 | L<BIO_f_base64(3)>, L<BIO_f_buffer(3)>, | |
65 | L<BIO_f_cipher(3)>, L<BIO_f_md(3)>, | |
66 | L<BIO_f_null(3)>, L<BIO_f_ssl(3)>, | |
67 | L<BIO_find_type(3)>, L<BIO_new(3)>, | |
68 | L<BIO_new_bio_pair(3)>, | |
b055fceb | 69 | L<BIO_push(3)>, L<BIO_read_ex(3)>, |
9b86974e RS |
70 | L<BIO_s_accept(3)>, L<BIO_s_bio(3)>, |
71 | L<BIO_s_connect(3)>, L<BIO_s_fd(3)>, | |
72 | L<BIO_s_file(3)>, L<BIO_s_mem(3)>, | |
9b86974e RS |
73 | L<BIO_s_null(3)>, L<BIO_s_socket(3)>, |
74 | L<BIO_set_callback(3)>, | |
75 | L<BIO_should_retry(3)> | |
99ec4fdb | 76 | |
e2f92610 RS |
77 | =head1 COPYRIGHT |
78 | ||
410e8c93 | 79 | Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 80 | |
3187791e | 81 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
82 | this file except in compliance with the License. You can obtain a copy |
83 | in the file LICENSE in the source distribution or at | |
84 | L<https://www.openssl.org/source/license.html>. | |
85 | ||
86 | =cut | |
53934822 | 87 |