1.\" $OpenBSD: BIO_s_file.3,v 1.16 2023/05/01 07:04:38 jsg 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: May 1 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.Fn BIO_set_fp 200is a macro. 201.Pp 202.Fn BIO_get_fp 203retrieves the file pointer of a file BIO, it is a macro. 204.Pp 205.Xr BIO_seek 3 206is a macro that sets the position pointer to 207.Fa offset 208bytes from the start of file. 209.Pp 210.Xr BIO_tell 3 211returns the value of the position pointer. 212.Pp 213.Fn BIO_read_filename , 214.Fn BIO_write_filename , 215.Fn BIO_append_filename , 216and 217.Fn BIO_rw_filename 218set the file BIO 219.Fa b 220to use file 221.Fa name 222for reading, writing, append or read write respectively. 223.Pp 224When wrapping stdout, stdin, or stderr, the underlying stream 225should not normally be closed, so the 226.Dv BIO_NOCLOSE 227flag should be set. 228.Pp 229Because the file BIO calls the underlying stdio functions, any quirks 230in stdio behaviour will be mirrored by the corresponding BIO. 231.Pp 232On Windows, 233.Fn BIO_new_files 234reserves for the filename argument to be UTF-8 encoded. 235In other words, if you have to make it work in a multi-lingual 236environment, encode file names in UTF-8. 237.Pp 238The following 239.Xr BIO_ctrl 3 240.Fa cmd 241constants correspond to macros: 242.Bl -column BIO_C_GET_FILE_PTR "corresponding macro" -offset 3n 243.It Fa cmd No constant Ta corresponding macro 244.It Dv BIO_C_FILE_SEEK Ta Xr BIO_seek 3 245.It Dv BIO_C_FILE_TELL Ta Xr BIO_tell 3 246.It Dv BIO_C_GET_FILE_PTR Ta Fn BIO_get_fp 247.It Dv BIO_C_SET_FILE_PTR Ta Fn BIO_set_fp 248.It Dv BIO_C_SET_FILENAME Ta various, see below 249.It Dv BIO_CTRL_EOF Ta Xr BIO_eof 3 250.It Dv BIO_CTRL_FLUSH Ta Xr BIO_flush 3 251.It Dv BIO_CTRL_GET_CLOSE Ta Xr BIO_get_close 3 252.It Dv BIO_CTRL_RESET Ta Xr BIO_reset 3 253.It Dv BIO_CTRL_SET_CLOSE Ta Xr BIO_set_close 3 254.El 255.Pp 256The meaning of 257.Dv BIO_C_SET_FILENAME 258depends on the flags passed in the 259.Xr BIO_ctrl 3 260.Fa larg 261argument: 262.Bl -column "BIO_CLOSE | BIO_FP_READ | BIO_FP_WRITE" "BIO_append_filename()"\ 263 -offset 3n 264.It Fa larg No argument Ta corresponding macro 265.It Dv BIO_CLOSE | BIO_FP_READ Ta Fn BIO_read_filename 266.It Dv BIO_CLOSE | BIO_FP_WRITE Ta Fn BIO_write_filename 267.It Dv BIO_CLOSE | BIO_FP_APPEND Ta Fn BIO_append_filename 268.It Dv BIO_CLOSE | BIO_FP_READ | BIO_FP_WRITE Ta Fn BIO_rw_filename 269.El 270.Sh RETURN VALUES 271.Fn BIO_s_file 272returns the file BIO method. 273.Pp 274.Fn BIO_new_file 275and 276.Fn BIO_new_fp 277return a file BIO or 278.Dv NULL 279if an error occurred. 280.Pp 281When called on a file BIO object, 282.Xr BIO_method_type 3 283returns the constant 284.Dv BIO_TYPE_FILE 285and 286.Xr BIO_method_name 3 287returns a pointer to the static string 288.Qq FILE pointer . 289.Pp 290.Fn BIO_set_fp 291and 292.Fn BIO_get_fp 293return 1 for success or 0 for failure (although the current 294implementation never returns 0). 295.Pp 296.Xr BIO_seek 3 297returns the same value as the underlying 298.Xr fseek 3 299function: 0 for success or -1 for failure. 300.Pp 301.Xr BIO_tell 3 302returns the current file position. 303.Pp 304.Fn BIO_read_filename , 305.Fn BIO_write_filename , 306.Fn BIO_append_filename , 307and 308.Fn BIO_rw_filename 309return 1 for success or 0 for failure. 310.Sh EXAMPLES 311File BIO "hello world": 312.Bd -literal -offset indent 313BIO *bio_out; 314bio_out = BIO_new_fp(stdout, BIO_NOCLOSE); 315BIO_printf(bio_out, "Hello World\en"); 316.Ed 317.Pp 318Alternative technique: 319.Bd -literal -offset indent 320BIO *bio_out; 321bio_out = BIO_new(BIO_s_file()); 322if(bio_out == NULL) /* Error ... */ 323if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */ 324BIO_printf(bio_out, "Hello World\en"); 325.Ed 326.Pp 327Write to a file: 328.Bd -literal -offset indent 329BIO *out; 330out = BIO_new_file("filename.txt", "w"); 331if(!out) /* Error occurred */ 332BIO_printf(out, "Hello World\en"); 333BIO_free(out); 334.Ed 335.Pp 336Alternative technique: 337.Bd -literal -offset indent 338BIO *out; 339out = BIO_new(BIO_s_file()); 340if(out == NULL) /* Error ... */ 341if(!BIO_write_filename(out, "filename.txt")) /* Error ... */ 342BIO_printf(out, "Hello World\en"); 343BIO_free(out); 344.Ed 345.Sh SEE ALSO 346.Xr BIO_new 3 , 347.Xr BIO_read 3 , 348.Xr BIO_seek 3 349.Sh HISTORY 350.Fn BIO_s_file , 351.Fn BIO_set_fp , 352.Fn BIO_get_fp , 353.Fn BIO_read_filename , 354.Fn BIO_write_filename , 355and 356.Fn BIO_append_filename 357first appeared in SSLeay 0.6.0. 358.Fn BIO_new_file 359and 360.Fn BIO_new_fp 361first appeared in SSLeay 0.8.0. 362All these functions have been available since 363.Ox 2.4 . 364.Pp 365.Fn BIO_rw_filename 366first appeared in SSLeay 0.9.1 and has been available since 367.Ox 2.6 . 368.Sh BUGS 369.Xr BIO_reset 3 370and 371.Xr BIO_seek 3 372are implemented using 373.Xr fseek 3 374on the underlying stream. 375The return value for 376.Xr fseek 3 377is 0 for success or -1 if an error occurred. 378This differs from other types of BIO which will typically return 3791 for success and a non-positive value if an error occurred. 380