]>
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 | ||
1bc74519 | 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 | ||
e17b7128 RL |
31 | Calls to BIO_read() and BIO_write() read and write data to the |
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 | ||
57 | BIO_set_fp() set the fp of a file BIO to B<fp>. B<flags> has the same | |
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 | ||
d7b9c76c DSH |
83 | =head1 EXAMPLES |
84 | ||
85 | File BIO "hello world": | |
86 | ||
87 | BIO *bio_out; | |
88 | bio_out = BIO_new_fp(stdout, BIO_NOCLOSE); | |
89 | BIO_printf(bio_out, "Hello World\n"); | |
90 | ||
91 | Alternative technique: | |
92 | ||
93 | BIO *bio_out; | |
94 | bio_out = BIO_new(BIO_s_file()); | |
2f8e53d7 F |
95 | if (bio_out == NULL) /* Error ... */ |
96 | if (!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */ | |
d7b9c76c DSH |
97 | BIO_printf(bio_out, "Hello World\n"); |
98 | ||
99 | Write to a file: | |
100 | ||
101 | BIO *out; | |
102 | out = BIO_new_file("filename.txt", "w"); | |
2f8e53d7 | 103 | if (!out) /* Error occurred */ |
d7b9c76c DSH |
104 | BIO_printf(out, "Hello World\n"); |
105 | BIO_free(out); | |
106 | ||
107 | Alternative technique: | |
108 | ||
109 | BIO *out; | |
110 | out = BIO_new(BIO_s_file()); | |
2f8e53d7 F |
111 | if (out == NULL) /* Error ... */ |
112 | if (!BIO_write_filename(out, "filename.txt")) /* Error ... */ | |
d7b9c76c DSH |
113 | BIO_printf(out, "Hello World\n"); |
114 | BIO_free(out); | |
115 | ||
116 | =head1 RETURN VALUES | |
117 | ||
118 | BIO_s_file() returns the file BIO method. | |
119 | ||
120 | BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error | |
121 | occurred. | |
122 | ||
123 | BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure | |
124 | (although the current implementation never return 0). | |
125 | ||
e17b7128 RL |
126 | BIO_seek() returns the same value as the underlying fseek() function: |
127 | 0 for success or -1 for failure. | |
128 | ||
129 | BIO_tell() returns the current file position. | |
130 | ||
0517ffc4 | 131 | BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and |
d7b9c76c DSH |
132 | BIO_rw_filename() return 1 for success or 0 for failure. |
133 | ||
3b2cbbcb DSH |
134 | =head1 BUGS |
135 | ||
136 | BIO_reset() and BIO_seek() are implemented using fseek() on the underlying | |
137 | stream. The return value for fseek() is 0 for success or -1 if an error | |
138 | occurred this differs from other types of BIO which will typically return | |
139 | 1 for success and a non positive value if an error occurred. | |
140 | ||
d7b9c76c DSH |
141 | =head1 SEE ALSO |
142 | ||
9b86974e RS |
143 | L<BIO_seek(3)>, L<BIO_tell(3)>, |
144 | L<BIO_reset(3)>, L<BIO_flush(3)>, | |
145 | L<BIO_read(3)>, | |
146 | L<BIO_write(3)>, L<BIO_puts(3)>, | |
147 | L<BIO_gets(3)>, L<BIO_printf(3)>, | |
148 | L<BIO_set_close(3)>, L<BIO_get_close(3)> | |
99ec4fdb | 149 | |
e2f92610 RS |
150 | =head1 COPYRIGHT |
151 | ||
152 | Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. | |
153 | ||
154 | Licensed under the OpenSSL license (the "License"). You may not use | |
155 | this file except in compliance with the License. You can obtain a copy | |
156 | in the file LICENSE in the source distribution or at | |
157 | L<https://www.openssl.org/source/license.html>. | |
158 | ||
159 | =cut |