1 files changed, 248 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/BIO_s_file.3 b/src/lib/libcrypto/man/BIO_s_file.3
new file mode 100644
index 0000000000..c7075a3fb7
--- /dev/null
+++ b/src/lib/libcrypto/man/BIO_s_file.3
@@ -0,0 +1,248 @@
+.Dd $Mdocdate: February 16 2015 $
+.Dt BIO_S_FILE 3
+.Os
+.Sh NAME
+.Nm BIO_s_file ,
+.Nm BIO_new_file ,
+.Nm BIO_new_fp ,
+.Nm BIO_set_fp ,
+.Nm BIO_get_fp ,
+.Nm BIO_read_filename ,
+.Nm BIO_write_filename ,
+.Nm BIO_append_filename ,
+.Nm BIO_rw_filename
+.Nd FILE bio
+.Sh SYNOPSIS
+.In openssl/bio.h
+.Ft BIO_METHOD *
+.Fo BIO_s_file
+.Fa void
+.Fc
+.Ft BIO *
+.Fo BIO_new_file
+.Fa "const char *filename"
+.Fa "const char *mode"
+.Fc
+.Ft BIO *
+.Fo BIO_new_fp
+.Fa "FILE *stream"
+.Fa "int flags"
+.Fc
+.Ft long
+.Fo BIO_set_fp
+.Fa "BIO *b"
+.Fa "FILE *fp"
+.Fa "int flags"
+.Fc
+.Ft long
+.Fo BIO_get_fp
+.Fa "BIO *b"
+.Fa "FILE **fpp"
+.Fc
+.Ft int
+.Fo BIO_read_filename
+.Fa "BIO *b"
+.Fa "char *name"
+.Fc
+.Ft int
+.Fo BIO_write_filename
+.Fa "BIO *b"
+.Fa "char *name"
+.Fc
+.Ft int
+.Fo BIO_append_filename
+.Fa "BIO *b"
+.Fa "char *name"
+.Fc
+.Ft int
+.Fo BIO_rw_filename
+.Fa "BIO *b"
+.Fa "char *name"
+.Fc
+.Sh DESCRIPTION
+.Fn BIO_s_file
+returns the BIO file method.
+As its name implies, it is a wrapper around the stdio
+.Vt FILE
+structure and it is a source/sink BIO.
+.Pp
+Calls to
+.Xr BIO_read 3
+and
+.Xr BIO_write 3
+read and write data to the underlying stream.
+.Xr BIO_gets 3
+and
+.Xr BIO_puts 3
+are supported on file BIOs.
+.Pp
+.Xr BIO_flush 3
+on a file BIO calls the
+.Xr fflush 3
+function on the wrapped stream.
+.Pp
+.Xr BIO_reset 3
+attempts to change the file pointer to the start of file using
+.Fn fseek stream 0 0 .
+.Pp
+.Xr BIO_seek 3
+sets the file pointer to position
+.Fa ofs
+from the start of the file using
+.Fn fseek stream ofs 0 .
+.Pp
+.Xr BIO_eof 3
+calls
+.Xr feof 3 .
+.Pp
+Setting the
+.Dv BIO_CLOSE
+flag calls
+.Xr fclose 3
+on the stream when the BIO is freed.
+.Pp
+.Fn BIO_new_file
+creates a new file BIO with mode
+.Fa mode .
+The meaning of
+.Fa mode
+is the same as for the stdio function
+.Xr fopen 3 .
+The
+.Dv BIO_CLOSE
+flag is set on the returned BIO.
+.Pp
+.Fn BIO_new_fp
+creates a file BIO wrapping
+.Fa stream .
+Flags can be:
+.Dv BIO_CLOSE , BIO_NOCLOSE Pq the close flag ,
+.Dv BIO_FP_TEXT
+(sets the underlying stream to text mode, default is binary:
+this only has any effect under Win32).
+.Pp
+.Fn BIO_set_fp
+set the file pointer of a file BIO to
+.Fa fp .
+.Fa flags
+has the same meaning as in
+.Fn BIO_new_fp .
+.Fn BIO_set_fp
+is a macro.
+.Pp
+.Fn BIO_get_fp
+retrieves the file pointer of a file BIO, it is a macro.
+.Pp
+.Xr BIO_seek 3
+is a macro that sets the position pointer to
+.Fa offset
+bytes from the start of file.
+.Pp
+.Xr BIO_tell 3
+returns the value of the position pointer.
+.Pp
+.Fn BIO_read_filename ,
+.Fn BIO_write_filename ,
+.Fn BIO_append_filename ,
+and
+.Fn BIO_rw_filename
+set the file BIO
+.Fa b
+to use file
+.Fa name
+for reading, writing, append or read write respectively.
+.Sh NOTES
+When wrapping stdout, stdin, or stderr, the underlying stream
+should not normally be closed, so the
+.Dv BIO_NOCLOSE
+flag should be set.
+.Pp
+Because the file BIO calls the underlying stdio functions, any quirks
+in stdio behaviour will be mirrored by the corresponding BIO.
+.Pp
+On Windows,
+.Fn BIO_new_files
+reserves for the filename argument to be UTF-8 encoded.
+In other words, if you have to make it work in a multi-lingual
+environment, encode file names in UTF-8.
+.Sh RETURN VALUES
+.Fn BIO_s_file
+returns the file BIO method.
+.Pp
+.Fn BIO_new_file
+and
+.Fn BIO_new_fp
+return a file BIO or
+.Dv NULL
+if an error occurred.
+.Pp
+.Fn BIO_set_fp
+and
+.Fn BIO_get_fp
+return 1 for success or 0 for failure (although the current
+implementation never returns 0).
+.Pp
+.Xr BIO_seek 3
+returns the same value as the underlying
+.Xr fseek 3
+function: 0 for success or -1 for failure.
+.Pp
+.Xr BIO_tell 3
+returns the current file position.
+.Pp
+.Fn BIO_read_filename ,
+.Fn BIO_write_filename ,
+.Fn BIO_append_filename ,
+and
+.Fn BIO_rw_filename
+return 1 for success or 0 for failure.
+.Sh EXAMPLES
+File BIO "hello world":
+.Bd -literal -offset indent
+BIO *bio_out;
+bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
+BIO_printf(bio_out, "Hello World\en");
+.Ed
+.Pp
+Alternative technique:
+.Bd -literal -offset indent
+BIO *bio_out;
+bio_out = BIO_new(BIO_s_file());
+if(bio_out == NULL) /* Error ... */
+if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */
+BIO_printf(bio_out, "Hello World\en");
+.Ed
+.Pp
+Write to a file:
+.Bd -literal -offset indent
+BIO *out;
+out = BIO_new_file("filename.txt", "w");
+if(!out) /* Error occurred */
+BIO_printf(out, "Hello World\en");
+BIO_free(out);
+.Ed
+.Pp
+Alternative technique:
+.Bd -literal -offset indent
+BIO *out;
+out = BIO_new(BIO_s_file());
+if(out == NULL) /* Error ... */
+if(!BIO_write_filename(out, "filename.txt")) /* Error ... */
+BIO_printf(out, "Hello World\en");
+BIO_free(out);
+.Ed
+.Sh SEE ALSO
+.Xr BIO_read 3 ,
+.Xr BIO_seek 3
+.Sh BUGS
+.Xr BIO_reset 3
+and
+.Xr BIO_seek 3
+are implemented using
+.Xr fseek 3
+on the underlying stream.
+The return value for
+.Xr fseek 3
+is 0 for success or -1 if an error occurred.
+This differs from other types of BIO which will typically return
+1 for success and a non positive value if an error occurred.