]>
Commit | Line | Data |
---|---|---|
d7b9c76c DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
8eec1389 RL |
5 | BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp, |
6 | BIO_read_filename, BIO_write_filename, BIO_append_filename, | |
7 | BIO_rw_filename - FILE bio | |
d7b9c76c DSH |
8 | |
9 | =head1 SYNOPSIS | |
10 | ||
11 | #include <openssl/bio.h> | |
12 | ||
e9b77246 | 13 | const BIO_METHOD *BIO_s_file(void); |
d7b9c76c DSH |
14 | BIO *BIO_new_file(const char *filename, const char *mode); |
15 | BIO *BIO_new_fp(FILE *stream, int flags); | |
16 | ||
aebb9aac RS |
17 | BIO_set_fp(BIO *b, FILE *fp, int flags); |
18 | BIO_get_fp(BIO *b, FILE **fpp); | |
d7b9c76c | 19 | |
d7b9c76c DSH |
20 | int BIO_read_filename(BIO *b, char *name) |
21 | int BIO_write_filename(BIO *b, char *name) | |
22 | int BIO_append_filename(BIO *b, char *name) | |
23 | int BIO_rw_filename(BIO *b, char *name) | |
24 | ||
25 | =head1 DESCRIPTION | |
26 | ||
27 | BIO_s_file() returns the BIO file method. As its name implies it | |
28 | is a wrapper round the stdio FILE structure and it is a | |
29 | source/sink BIO. | |
30 | ||
b055fceb | 31 | Calls to BIO_read_ex() and BIO_write_ex() read and write data to the |
e17b7128 RL |
32 | underlying stream. BIO_gets() and BIO_puts() are supported on file BIOs. |
33 | ||
34 | BIO_flush() on a file BIO calls the fflush() function on the wrapped | |
35 | stream. | |
36 | ||
37 | BIO_reset() attempts to change the file pointer to the start of file | |
38 | using fseek(stream, 0, 0). | |
39 | ||
40 | BIO_seek() sets the file pointer to position B<ofs> from start of file | |
3b2cbbcb | 41 | using fseek(stream, ofs, 0). |
e17b7128 RL |
42 | |
43 | BIO_eof() calls feof(). | |
44 | ||
45 | Setting the BIO_CLOSE flag calls fclose() on the stream when the BIO | |
46 | is freed. | |
47 | ||
d7b9c76c DSH |
48 | BIO_new_file() creates a new file BIO with mode B<mode> the meaning |
49 | of B<mode> is the same as the stdio function fopen(). The BIO_CLOSE | |
50 | flag is set on the returned BIO. | |
51 | ||
52 | BIO_new_fp() creates a file BIO wrapping B<stream>. Flags can be: | |
53 | BIO_CLOSE, BIO_NOCLOSE (the close flag) BIO_FP_TEXT (sets the underlying | |
54 | stream to text mode, default is binary: this only has any effect under | |
55 | Win32). | |
56 | ||
a21285b3 | 57 | BIO_set_fp() sets the fp of a file BIO to B<fp>. B<flags> has the same |
d7b9c76c DSH |
58 | meaning as in BIO_new_fp(), it is a macro. |
59 | ||
60 | BIO_get_fp() retrieves the fp of a file BIO, it is a macro. | |
61 | ||
e17b7128 RL |
62 | BIO_seek() is a macro that sets the position pointer to B<offset> bytes |
63 | from the start of file. | |
64 | ||
65 | BIO_tell() returns the value of the position pointer. | |
66 | ||
d7b9c76c DSH |
67 | BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and |
68 | BIO_rw_filename() set the file BIO B<b> to use file B<name> for | |
69 | reading, writing, append or read write respectively. | |
70 | ||
71 | =head1 NOTES | |
72 | ||
73 | When wrapping stdout, stdin or stderr the underlying stream should not | |
74 | normally be closed so the BIO_NOCLOSE flag should be set. | |
75 | ||
76 | Because the file BIO calls the underlying stdio functions any quirks | |
acb5b343 | 77 | in stdio behaviour will be mirrored by the corresponding BIO. |
d7b9c76c | 78 | |
bb92e2c8 AP |
79 | On Windows BIO_new_files reserves for the filename argument to be |
80 | UTF-8 encoded. In other words if you have to make it work in multi- | |
81 | lingual environment, encode file names in UTF-8. | |
82 | ||
4564e77a PY |
83 | =head1 RETURN VALUES |
84 | ||
85 | BIO_s_file() returns the file BIO method. | |
86 | ||
87 | BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error | |
88 | occurred. | |
89 | ||
90 | BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure | |
91 | (although the current implementation never return 0). | |
92 | ||
93 | BIO_seek() returns the same value as the underlying fseek() function: | |
94 | 0 for success or -1 for failure. | |
95 | ||
96 | BIO_tell() returns the current file position. | |
97 | ||
98 | BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and | |
99 | BIO_rw_filename() return 1 for success or 0 for failure. | |
100 | ||
d7b9c76c DSH |
101 | =head1 EXAMPLES |
102 | ||
103 | File BIO "hello world": | |
104 | ||
105 | BIO *bio_out; | |
e9b77246 | 106 | |
d7b9c76c DSH |
107 | bio_out = BIO_new_fp(stdout, BIO_NOCLOSE); |
108 | BIO_printf(bio_out, "Hello World\n"); | |
109 | ||
110 | Alternative technique: | |
111 | ||
112 | BIO *bio_out; | |
e9b77246 | 113 | |
d7b9c76c | 114 | bio_out = BIO_new(BIO_s_file()); |
2947af32 BB |
115 | if (bio_out == NULL) |
116 | /* Error */ | |
117 | if (!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) | |
118 | /* Error */ | |
d7b9c76c DSH |
119 | BIO_printf(bio_out, "Hello World\n"); |
120 | ||
121 | Write to a file: | |
122 | ||
123 | BIO *out; | |
e9b77246 | 124 | |
d7b9c76c | 125 | out = BIO_new_file("filename.txt", "w"); |
2947af32 BB |
126 | if (!out) |
127 | /* Error */ | |
d7b9c76c DSH |
128 | BIO_printf(out, "Hello World\n"); |
129 | BIO_free(out); | |
130 | ||
131 | Alternative technique: | |
132 | ||
133 | BIO *out; | |
e9b77246 | 134 | |
d7b9c76c | 135 | out = BIO_new(BIO_s_file()); |
2947af32 BB |
136 | if (out == NULL) |
137 | /* Error */ | |
138 | if (!BIO_write_filename(out, "filename.txt")) | |
139 | /* Error */ | |
d7b9c76c DSH |
140 | BIO_printf(out, "Hello World\n"); |
141 | BIO_free(out); | |
142 | ||
3b2cbbcb DSH |
143 | =head1 BUGS |
144 | ||
145 | BIO_reset() and BIO_seek() are implemented using fseek() on the underlying | |
146 | stream. The return value for fseek() is 0 for success or -1 if an error | |
147 | occurred this differs from other types of BIO which will typically return | |
148 | 1 for success and a non positive value if an error occurred. | |
149 | ||
d7b9c76c DSH |
150 | =head1 SEE ALSO |
151 | ||
9b86974e RS |
152 | L<BIO_seek(3)>, L<BIO_tell(3)>, |
153 | L<BIO_reset(3)>, L<BIO_flush(3)>, | |
b055fceb MC |
154 | L<BIO_read_ex(3)>, |
155 | L<BIO_write_ex(3)>, L<BIO_puts(3)>, | |
9b86974e RS |
156 | L<BIO_gets(3)>, L<BIO_printf(3)>, |
157 | L<BIO_set_close(3)>, L<BIO_get_close(3)> | |
99ec4fdb | 158 | |
e2f92610 RS |
159 | =head1 COPYRIGHT |
160 | ||
1212818e | 161 | Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 162 | |
4746f25a | 163 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
164 | this file except in compliance with the License. You can obtain a copy |
165 | in the file LICENSE in the source distribution or at | |
166 | L<https://www.openssl.org/source/license.html>. | |
167 | ||
168 | =cut |