1.\" $OpenBSD: BIO_s_file.3,v 1.17 2023/11/16 20:19:23 schwarze Exp $ 2.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 3.\" selective merge up to: OpenSSL 1212818e Sep 11 13:22:14 2018 +0100 4.\" 5.\" This file is a derived work. 6.\" The changes are covered by the following Copyright and license: 7.\" 8.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org> 9.\" 10.\" Permission to use, copy, modify, and distribute this software for any 11.\" purpose with or without fee is hereby granted, provided that the above 12.\" copyright notice and this permission notice appear in all copies. 13.\" 14.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 15.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 16.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 17.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 18.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 19.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 20.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 21.\" 22.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 23.\" Copyright (c) 2000, 2010 The OpenSSL Project. All rights reserved. 24.\" 25.\" Redistribution and use in source and binary forms, with or without 26.\" modification, are permitted provided that the following conditions 27.\" are met: 28.\" 29.\" 1. Redistributions of source code must retain the above copyright 30.\" notice, this list of conditions and the following disclaimer. 31.\" 32.\" 2. Redistributions in binary form must reproduce the above copyright 33.\" notice, this list of conditions and the following disclaimer in 34.\" the documentation and/or other materials provided with the 35.\" distribution. 36.\" 37.\" 3. All advertising materials mentioning features or use of this 38.\" software must display the following acknowledgment: 39.\" "This product includes software developed by the OpenSSL Project 40.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 41.\" 42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 43.\" endorse or promote products derived from this software without 44.\" prior written permission. For written permission, please contact 45.\" openssl-core@openssl.org. 46.\" 47.\" 5. Products derived from this software may not be called "OpenSSL" 48.\" nor may "OpenSSL" appear in their names without prior written 49.\" permission of the OpenSSL Project. 50.\" 51.\" 6. Redistributions of any form whatsoever must retain the following 52.\" acknowledgment: 53.\" "This product includes software developed by the OpenSSL Project 54.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 55.\" 56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 59.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 67.\" OF THE POSSIBILITY OF SUCH DAMAGE. 68.\" 69.Dd $Mdocdate: November 16 2023 $ 70.Dt BIO_S_FILE 3 71.Os 72.Sh NAME 73.Nm BIO_s_file , 74.Nm BIO_new_file , 75.Nm BIO_new_fp , 76.Nm BIO_set_fp , 77.Nm BIO_get_fp , 78.Nm BIO_read_filename , 79.Nm BIO_write_filename , 80.Nm BIO_append_filename , 81.Nm BIO_rw_filename 82.\" Nm BIO_CTRL_SET_FILENAME is unused and intentionally undocumented. 83.Nd FILE BIO 84.Sh SYNOPSIS 85.In openssl/bio.h 86.Ft const BIO_METHOD * 87.Fo BIO_s_file 88.Fa void 89.Fc 90.Ft BIO * 91.Fo BIO_new_file 92.Fa "const char *filename" 93.Fa "const char *mode" 94.Fc 95.Ft BIO * 96.Fo BIO_new_fp 97.Fa "FILE *stream" 98.Fa "int flags" 99.Fc 100.Ft long 101.Fo BIO_set_fp 102.Fa "BIO *b" 103.Fa "FILE *fp" 104.Fa "int flags" 105.Fc 106.Ft long 107.Fo BIO_get_fp 108.Fa "BIO *b" 109.Fa "FILE **fpp" 110.Fc 111.Ft long 112.Fo BIO_read_filename 113.Fa "BIO *b" 114.Fa "char *name" 115.Fc 116.Ft long 117.Fo BIO_write_filename 118.Fa "BIO *b" 119.Fa "char *name" 120.Fc 121.Ft long 122.Fo BIO_append_filename 123.Fa "BIO *b" 124.Fa "char *name" 125.Fc 126.Ft long 127.Fo BIO_rw_filename 128.Fa "BIO *b" 129.Fa "char *name" 130.Fc 131.Sh DESCRIPTION 132.Fn BIO_s_file 133returns the BIO file method. 134As its name implies, it is a wrapper around the stdio 135.Vt FILE 136structure and it is a source/sink BIO. 137.Pp 138Calls to 139.Xr BIO_read 3 140and 141.Xr BIO_write 3 142read and write data to the underlying stream. 143.Xr BIO_gets 3 144and 145.Xr BIO_puts 3 146are supported on file BIOs. 147.Pp 148.Xr BIO_flush 3 149on a file BIO calls the 150.Xr fflush 3 151function on the wrapped stream. 152.Pp 153.Xr BIO_reset 3 154attempts to change the file pointer to the start of file using 155.Fn fseek stream 0 0 . 156.Pp 157.Xr BIO_seek 3 158sets the file pointer to position 159.Fa ofs 160from the start of the file using 161.Fn fseek stream ofs 0 . 162.Pp 163.Xr BIO_eof 3 164calls 165.Xr feof 3 . 166.Pp 167Setting the 168.Dv BIO_CLOSE 169flag calls 170.Xr fclose 3 171on the stream when the BIO is freed. 172.Pp 173.Fn BIO_new_file 174creates a new file BIO with mode 175.Fa mode . 176The meaning of 177.Fa mode 178is the same as for the stdio function 179.Xr fopen 3 . 180The 181.Dv BIO_CLOSE 182flag is set on the returned BIO. 183.Pp 184.Fn BIO_new_fp 185creates a file BIO wrapping 186.Fa stream . 187Flags can be: 188.Dv BIO_CLOSE , BIO_NOCLOSE Pq the close flag , 189.Dv BIO_FP_TEXT 190(sets the underlying stream to text mode, default is binary: 191this only has any effect under Win32). 192.Pp 193.Fn BIO_set_fp 194sets the file pointer of a file BIO to 195.Fa fp . 196.Fa flags 197has the same meaning as in 198.Fn BIO_new_fp . 199.Pp 200.Fn BIO_get_fp 201retrieves the file pointer of a file BIO. 202.Pp 203.Xr BIO_seek 3 204sets the position pointer to 205.Fa offset 206bytes from the start of file. 207.Pp 208.Xr BIO_tell 3 209returns the value of the position pointer. 210.Pp 211.Fn BIO_read_filename , 212.Fn BIO_write_filename , 213.Fn BIO_append_filename , 214and 215.Fn BIO_rw_filename 216set the file BIO 217.Fa b 218to use file 219.Fa name 220for reading, writing, append or read write respectively. 221.Pp 222When wrapping stdout, stdin, or stderr, the underlying stream 223should not normally be closed, so the 224.Dv BIO_NOCLOSE 225flag should be set. 226.Pp 227Because the file BIO calls the underlying stdio functions, any quirks 228in stdio behaviour will be mirrored by the corresponding BIO. 229.Pp 230On Windows, 231.Fn BIO_new_files 232reserves for the filename argument to be UTF-8 encoded. 233In other words, if you have to make it work in a multi-lingual 234environment, encode file names in UTF-8. 235.Pp 236The following 237.Xr BIO_ctrl 3 238.Fa cmd 239constants correspond to macros: 240.Bl -column BIO_C_GET_FILE_PTR "corresponding macro" -offset 3n 241.It Fa cmd No constant Ta corresponding macro 242.It Dv BIO_C_FILE_SEEK Ta Xr BIO_seek 3 243.It Dv BIO_C_FILE_TELL Ta Xr BIO_tell 3 244.It Dv BIO_C_GET_FILE_PTR Ta Fn BIO_get_fp 245.It Dv BIO_C_SET_FILE_PTR Ta Fn BIO_set_fp 246.It Dv BIO_C_SET_FILENAME Ta various, see below 247.It Dv BIO_CTRL_EOF Ta Xr BIO_eof 3 248.It Dv BIO_CTRL_FLUSH Ta Xr BIO_flush 3 249.It Dv BIO_CTRL_GET_CLOSE Ta Xr BIO_get_close 3 250.It Dv BIO_CTRL_RESET Ta Xr BIO_reset 3 251.It Dv BIO_CTRL_SET_CLOSE Ta Xr BIO_set_close 3 252.El 253.Pp 254The meaning of 255.Dv BIO_C_SET_FILENAME 256depends on the flags passed in the 257.Xr BIO_ctrl 3 258.Fa larg 259argument: 260.Bl -column "BIO_CLOSE | BIO_FP_READ | BIO_FP_WRITE" "BIO_append_filename()"\ 261 -offset 3n 262.It Fa larg No argument Ta corresponding macro 263.It Dv BIO_CLOSE | BIO_FP_READ Ta Fn BIO_read_filename 264.It Dv BIO_CLOSE | BIO_FP_WRITE Ta Fn BIO_write_filename 265.It Dv BIO_CLOSE | BIO_FP_APPEND Ta Fn BIO_append_filename 266.It Dv BIO_CLOSE | BIO_FP_READ | BIO_FP_WRITE Ta Fn BIO_rw_filename 267.El 268.Sh RETURN VALUES 269.Fn BIO_s_file 270returns the file BIO method. 271.Pp 272.Fn BIO_new_file 273and 274.Fn BIO_new_fp 275return a file BIO or 276.Dv NULL 277if an error occurred. 278.Pp 279When called on a file BIO object, 280.Xr BIO_method_type 3 281returns the constant 282.Dv BIO_TYPE_FILE 283and 284.Xr BIO_method_name 3 285returns a pointer to the static string 286.Qq FILE pointer . 287.Pp 288.Fn BIO_set_fp 289and 290.Fn BIO_get_fp 291return 1 for success or 0 for failure (although the current 292implementation never returns 0). 293.Pp 294.Xr BIO_seek 3 295returns the same value as the underlying 296.Xr fseek 3 297function: 0 for success or -1 for failure. 298.Pp 299.Xr BIO_tell 3 300returns the current file position. 301.Pp 302.Fn BIO_read_filename , 303.Fn BIO_write_filename , 304.Fn BIO_append_filename , 305and 306.Fn BIO_rw_filename 307return 1 for success or 0 for failure. 308.Sh EXAMPLES 309File BIO "hello world": 310.Bd -literal -offset indent 311BIO *bio_out; 312bio_out = BIO_new_fp(stdout, BIO_NOCLOSE); 313BIO_printf(bio_out, "Hello World\en"); 314.Ed 315.Pp 316Alternative technique: 317.Bd -literal -offset indent 318BIO *bio_out; 319bio_out = BIO_new(BIO_s_file()); 320if(bio_out == NULL) /* Error ... */ 321if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */ 322BIO_printf(bio_out, "Hello World\en"); 323.Ed 324.Pp 325Write to a file: 326.Bd -literal -offset indent 327BIO *out; 328out = BIO_new_file("filename.txt", "w"); 329if(!out) /* Error occurred */ 330BIO_printf(out, "Hello World\en"); 331BIO_free(out); 332.Ed 333.Pp 334Alternative technique: 335.Bd -literal -offset indent 336BIO *out; 337out = BIO_new(BIO_s_file()); 338if(out == NULL) /* Error ... */ 339if(!BIO_write_filename(out, "filename.txt")) /* Error ... */ 340BIO_printf(out, "Hello World\en"); 341BIO_free(out); 342.Ed 343.Sh SEE ALSO 344.Xr BIO_new 3 , 345.Xr BIO_read 3 , 346.Xr BIO_seek 3 347.Sh HISTORY 348.Fn BIO_s_file , 349.Fn BIO_set_fp , 350.Fn BIO_get_fp , 351.Fn BIO_read_filename , 352.Fn BIO_write_filename , 353and 354.Fn BIO_append_filename 355first appeared in SSLeay 0.6.0. 356.Fn BIO_new_file 357and 358.Fn BIO_new_fp 359first appeared in SSLeay 0.8.0. 360All these functions have been available since 361.Ox 2.4 . 362.Pp 363.Fn BIO_rw_filename 364first appeared in SSLeay 0.9.1 and has been available since 365.Ox 2.6 . 366.Sh BUGS 367.Xr BIO_reset 3 368and 369.Xr BIO_seek 3 370are implemented using 371.Xr fseek 3 372on the underlying stream. 373The return value for 374.Xr fseek 3 375is 0 for success or -1 if an error occurred. 376This differs from other types of BIO which will typically return 3771 for success and a non-positive value if an error occurred. 378