From eb8dd9dca1228af0cd132f515509051ecfabf6f6 Mon Sep 17 00:00:00 2001 From: cvs2svn Date: Mon, 14 Apr 2025 17:32:06 +0000 Subject: This commit was manufactured by cvs2git to create tag 'tb_20250414'. --- src/lib/libcrypto/man/BIO_s_file.3 | 377 ------------------------------------- 1 file changed, 377 deletions(-) delete mode 100644 src/lib/libcrypto/man/BIO_s_file.3 (limited to 'src/lib/libcrypto/man/BIO_s_file.3') diff --git a/src/lib/libcrypto/man/BIO_s_file.3 b/src/lib/libcrypto/man/BIO_s_file.3 deleted file mode 100644 index 14950cad13..0000000000 --- a/src/lib/libcrypto/man/BIO_s_file.3 +++ /dev/null @@ -1,377 +0,0 @@ -.\" $OpenBSD: BIO_s_file.3,v 1.17 2023/11/16 20:19:23 schwarze 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 -.\" -.\" 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 . -.\" 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: November 16 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 . -.Pp -.Fn BIO_get_fp -retrieves the file pointer of a file BIO. -.Pp -.Xr BIO_seek 3 -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. -- cgit v1.2.3-55-g6feb