1.Dd $Mdocdate: February 16 2015 $ 2.Dt BIO_S_FILE 3 3.Os 4.Sh NAME 5.Nm BIO_s_file , 6.Nm BIO_new_file , 7.Nm BIO_new_fp , 8.Nm BIO_set_fp , 9.Nm BIO_get_fp , 10.Nm BIO_read_filename , 11.Nm BIO_write_filename , 12.Nm BIO_append_filename , 13.Nm BIO_rw_filename 14.Nd FILE bio 15.Sh SYNOPSIS 16.In openssl/bio.h 17.Ft BIO_METHOD * 18.Fo BIO_s_file 19.Fa void 20.Fc 21.Ft BIO * 22.Fo BIO_new_file 23.Fa "const char *filename" 24.Fa "const char *mode" 25.Fc 26.Ft BIO * 27.Fo BIO_new_fp 28.Fa "FILE *stream" 29.Fa "int flags" 30.Fc 31.Ft long 32.Fo BIO_set_fp 33.Fa "BIO *b" 34.Fa "FILE *fp" 35.Fa "int flags" 36.Fc 37.Ft long 38.Fo BIO_get_fp 39.Fa "BIO *b" 40.Fa "FILE **fpp" 41.Fc 42.Ft int 43.Fo BIO_read_filename 44.Fa "BIO *b" 45.Fa "char *name" 46.Fc 47.Ft int 48.Fo BIO_write_filename 49.Fa "BIO *b" 50.Fa "char *name" 51.Fc 52.Ft int 53.Fo BIO_append_filename 54.Fa "BIO *b" 55.Fa "char *name" 56.Fc 57.Ft int 58.Fo BIO_rw_filename 59.Fa "BIO *b" 60.Fa "char *name" 61.Fc 62.Sh DESCRIPTION 63.Fn BIO_s_file 64returns the BIO file method. 65As its name implies, it is a wrapper around the stdio 66.Vt FILE 67structure and it is a source/sink BIO. 68.Pp 69Calls to 70.Xr BIO_read 3 71and 72.Xr BIO_write 3 73read and write data to the underlying stream. 74.Xr BIO_gets 3 75and 76.Xr BIO_puts 3 77are supported on file BIOs. 78.Pp 79.Xr BIO_flush 3 80on a file BIO calls the 81.Xr fflush 3 82function on the wrapped stream. 83.Pp 84.Xr BIO_reset 3 85attempts to change the file pointer to the start of file using 86.Fn fseek stream 0 0 . 87.Pp 88.Xr BIO_seek 3 89sets the file pointer to position 90.Fa ofs 91from the start of the file using 92.Fn fseek stream ofs 0 . 93.Pp 94.Xr BIO_eof 3 95calls 96.Xr feof 3 . 97.Pp 98Setting the 99.Dv BIO_CLOSE 100flag calls 101.Xr fclose 3 102on the stream when the BIO is freed. 103.Pp 104.Fn BIO_new_file 105creates a new file BIO with mode 106.Fa mode . 107The meaning of 108.Fa mode 109is the same as for the stdio function 110.Xr fopen 3 . 111The 112.Dv BIO_CLOSE 113flag is set on the returned BIO. 114.Pp 115.Fn BIO_new_fp 116creates a file BIO wrapping 117.Fa stream . 118Flags can be: 119.Dv BIO_CLOSE , BIO_NOCLOSE Pq the close flag , 120.Dv BIO_FP_TEXT 121(sets the underlying stream to text mode, default is binary: 122this only has any effect under Win32). 123.Pp 124.Fn BIO_set_fp 125set the file pointer of a file BIO to 126.Fa fp . 127.Fa flags 128has the same meaning as in 129.Fn BIO_new_fp . 130.Fn BIO_set_fp 131is a macro. 132.Pp 133.Fn BIO_get_fp 134retrieves the file pointer of a file BIO, it is a macro. 135.Pp 136.Xr BIO_seek 3 137is a macro that sets the position pointer to 138.Fa offset 139bytes from the start of file. 140.Pp 141.Xr BIO_tell 3 142returns the value of the position pointer. 143.Pp 144.Fn BIO_read_filename , 145.Fn BIO_write_filename , 146.Fn BIO_append_filename , 147and 148.Fn BIO_rw_filename 149set the file BIO 150.Fa b 151to use file 152.Fa name 153for reading, writing, append or read write respectively. 154.Sh NOTES 155When wrapping stdout, stdin, or stderr, the underlying stream 156should not normally be closed, so the 157.Dv BIO_NOCLOSE 158flag should be set. 159.Pp 160Because the file BIO calls the underlying stdio functions, any quirks 161in stdio behaviour will be mirrored by the corresponding BIO. 162.Pp 163On Windows, 164.Fn BIO_new_files 165reserves for the filename argument to be UTF-8 encoded. 166In other words, if you have to make it work in a multi-lingual 167environment, encode file names in UTF-8. 168.Sh RETURN VALUES 169.Fn BIO_s_file 170returns the file BIO method. 171.Pp 172.Fn BIO_new_file 173and 174.Fn BIO_new_fp 175return a file BIO or 176.Dv NULL 177if an error occurred. 178.Pp 179.Fn BIO_set_fp 180and 181.Fn BIO_get_fp 182return 1 for success or 0 for failure (although the current 183implementation never returns 0). 184.Pp 185.Xr BIO_seek 3 186returns the same value as the underlying 187.Xr fseek 3 188function: 0 for success or -1 for failure. 189.Pp 190.Xr BIO_tell 3 191returns the current file position. 192.Pp 193.Fn BIO_read_filename , 194.Fn BIO_write_filename , 195.Fn BIO_append_filename , 196and 197.Fn BIO_rw_filename 198return 1 for success or 0 for failure. 199.Sh EXAMPLES 200File BIO "hello world": 201.Bd -literal -offset indent 202BIO *bio_out; 203bio_out = BIO_new_fp(stdout, BIO_NOCLOSE); 204BIO_printf(bio_out, "Hello World\en"); 205.Ed 206.Pp 207Alternative technique: 208.Bd -literal -offset indent 209BIO *bio_out; 210bio_out = BIO_new(BIO_s_file()); 211if(bio_out == NULL) /* Error ... */ 212if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */ 213BIO_printf(bio_out, "Hello World\en"); 214.Ed 215.Pp 216Write to a file: 217.Bd -literal -offset indent 218BIO *out; 219out = BIO_new_file("filename.txt", "w"); 220if(!out) /* Error occurred */ 221BIO_printf(out, "Hello World\en"); 222BIO_free(out); 223.Ed 224.Pp 225Alternative technique: 226.Bd -literal -offset indent 227BIO *out; 228out = BIO_new(BIO_s_file()); 229if(out == NULL) /* Error ... */ 230if(!BIO_write_filename(out, "filename.txt")) /* Error ... */ 231BIO_printf(out, "Hello World\en"); 232BIO_free(out); 233.Ed 234.Sh SEE ALSO 235.Xr BIO_read 3 , 236.Xr BIO_seek 3 237.Sh BUGS 238.Xr BIO_reset 3 239and 240.Xr BIO_seek 3 241are implemented using 242.Xr fseek 3 243on the underlying stream. 244The return value for 245.Xr fseek 3 246is 0 for success or -1 if an error occurred. 247This differs from other types of BIO which will typically return 2481 for success and a non positive value if an error occurred. 249