379 lines
10 KiB
Groff
379 lines
10 KiB
Groff
.\" $OpenBSD: BIO_s_file.3,v 1.16 2023/05/01 07:04:38 jsg Exp $
|
|
.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
|
|
.\" selective merge up to: OpenSSL 1212818e Sep 11 13:22:14 2018 +0100
|
|
.\"
|
|
.\" This file is a derived work.
|
|
.\" The changes are covered by the following Copyright and license:
|
|
.\"
|
|
.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org>
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
|
|
.\" Copyright (c) 2000, 2010 The OpenSSL Project. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\"
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\"
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in
|
|
.\" the documentation and/or other materials provided with the
|
|
.\" distribution.
|
|
.\"
|
|
.\" 3. All advertising materials mentioning features or use of this
|
|
.\" software must display the following acknowledgment:
|
|
.\" "This product includes software developed by the OpenSSL Project
|
|
.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
|
|
.\"
|
|
.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
|
|
.\" endorse or promote products derived from this software without
|
|
.\" prior written permission. For written permission, please contact
|
|
.\" openssl-core@openssl.org.
|
|
.\"
|
|
.\" 5. Products derived from this software may not be called "OpenSSL"
|
|
.\" nor may "OpenSSL" appear in their names without prior written
|
|
.\" permission of the OpenSSL Project.
|
|
.\"
|
|
.\" 6. Redistributions of any form whatsoever must retain the following
|
|
.\" acknowledgment:
|
|
.\" "This product includes software developed by the OpenSSL Project
|
|
.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
|
|
.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
|
|
.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
|
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
|
|
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
|
|
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd $Mdocdate: May 1 2023 $
|
|
.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
|
|
.\" Nm BIO_CTRL_SET_FILENAME is unused and intentionally undocumented.
|
|
.Nd FILE BIO
|
|
.Sh SYNOPSIS
|
|
.In openssl/bio.h
|
|
.Ft const 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 long
|
|
.Fo BIO_read_filename
|
|
.Fa "BIO *b"
|
|
.Fa "char *name"
|
|
.Fc
|
|
.Ft long
|
|
.Fo BIO_write_filename
|
|
.Fa "BIO *b"
|
|
.Fa "char *name"
|
|
.Fc
|
|
.Ft long
|
|
.Fo BIO_append_filename
|
|
.Fa "BIO *b"
|
|
.Fa "char *name"
|
|
.Fc
|
|
.Ft long
|
|
.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
|
|
sets 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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
The following
|
|
.Xr BIO_ctrl 3
|
|
.Fa cmd
|
|
constants correspond to macros:
|
|
.Bl -column BIO_C_GET_FILE_PTR "corresponding macro" -offset 3n
|
|
.It Fa cmd No constant Ta corresponding macro
|
|
.It Dv BIO_C_FILE_SEEK Ta Xr BIO_seek 3
|
|
.It Dv BIO_C_FILE_TELL Ta Xr BIO_tell 3
|
|
.It Dv BIO_C_GET_FILE_PTR Ta Fn BIO_get_fp
|
|
.It Dv BIO_C_SET_FILE_PTR Ta Fn BIO_set_fp
|
|
.It Dv BIO_C_SET_FILENAME Ta various, see below
|
|
.It Dv BIO_CTRL_EOF Ta Xr BIO_eof 3
|
|
.It Dv BIO_CTRL_FLUSH Ta Xr BIO_flush 3
|
|
.It Dv BIO_CTRL_GET_CLOSE Ta Xr BIO_get_close 3
|
|
.It Dv BIO_CTRL_RESET Ta Xr BIO_reset 3
|
|
.It Dv BIO_CTRL_SET_CLOSE Ta Xr BIO_set_close 3
|
|
.El
|
|
.Pp
|
|
The meaning of
|
|
.Dv BIO_C_SET_FILENAME
|
|
depends on the flags passed in the
|
|
.Xr BIO_ctrl 3
|
|
.Fa larg
|
|
argument:
|
|
.Bl -column "BIO_CLOSE | BIO_FP_READ | BIO_FP_WRITE" "BIO_append_filename()"\
|
|
-offset 3n
|
|
.It Fa larg No argument Ta corresponding macro
|
|
.It Dv BIO_CLOSE | BIO_FP_READ Ta Fn BIO_read_filename
|
|
.It Dv BIO_CLOSE | BIO_FP_WRITE Ta Fn BIO_write_filename
|
|
.It Dv BIO_CLOSE | BIO_FP_APPEND Ta Fn BIO_append_filename
|
|
.It Dv BIO_CLOSE | BIO_FP_READ | BIO_FP_WRITE Ta Fn BIO_rw_filename
|
|
.El
|
|
.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
|
|
When called on a file BIO object,
|
|
.Xr BIO_method_type 3
|
|
returns the constant
|
|
.Dv BIO_TYPE_FILE
|
|
and
|
|
.Xr BIO_method_name 3
|
|
returns a pointer to the static string
|
|
.Qq FILE pointer .
|
|
.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_new 3 ,
|
|
.Xr BIO_read 3 ,
|
|
.Xr BIO_seek 3
|
|
.Sh HISTORY
|
|
.Fn BIO_s_file ,
|
|
.Fn BIO_set_fp ,
|
|
.Fn BIO_get_fp ,
|
|
.Fn BIO_read_filename ,
|
|
.Fn BIO_write_filename ,
|
|
and
|
|
.Fn BIO_append_filename
|
|
first appeared in SSLeay 0.6.0.
|
|
.Fn BIO_new_file
|
|
and
|
|
.Fn BIO_new_fp
|
|
first appeared in SSLeay 0.8.0.
|
|
All these functions have been available since
|
|
.Ox 2.4 .
|
|
.Pp
|
|
.Fn BIO_rw_filename
|
|
first appeared in SSLeay 0.9.1 and has been available since
|
|
.Ox 2.6 .
|
|
.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.
|