summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/BIO_s_fd.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/lib/libcrypto/man/BIO_s_fd.3290
1 files changed, 0 insertions, 290 deletions
diff --git a/src/lib/libcrypto/man/BIO_s_fd.3 b/src/lib/libcrypto/man/BIO_s_fd.3
deleted file mode 100644
index 852a06756a..0000000000
--- a/src/lib/libcrypto/man/BIO_s_fd.3
+++ /dev/null
@@ -1,290 +0,0 @@
1.\" $OpenBSD: BIO_s_fd.3,v 1.13 2023/11/16 20:19:23 schwarze Exp $
2.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
3.\"
4.\" This file is a derived work.
5.\" The changes are covered by the following Copyright and license:
6.\"
7.\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org>
8.\"
9.\" Permission to use, copy, modify, and distribute this software for any
10.\" purpose with or without fee is hereby granted, provided that the above
11.\" copyright notice and this permission notice appear in all copies.
12.\"
13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20.\"
21.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
22.\" Copyright (c) 2000 The OpenSSL Project. All rights reserved.
23.\"
24.\" Redistribution and use in source and binary forms, with or without
25.\" modification, are permitted provided that the following conditions
26.\" are met:
27.\"
28.\" 1. Redistributions of source code must retain the above copyright
29.\" notice, this list of conditions and the following disclaimer.
30.\"
31.\" 2. Redistributions in binary form must reproduce the above copyright
32.\" notice, this list of conditions and the following disclaimer in
33.\" the documentation and/or other materials provided with the
34.\" distribution.
35.\"
36.\" 3. All advertising materials mentioning features or use of this
37.\" software must display the following acknowledgment:
38.\" "This product includes software developed by the OpenSSL Project
39.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
40.\"
41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
42.\" endorse or promote products derived from this software without
43.\" prior written permission. For written permission, please contact
44.\" openssl-core@openssl.org.
45.\"
46.\" 5. Products derived from this software may not be called "OpenSSL"
47.\" nor may "OpenSSL" appear in their names without prior written
48.\" permission of the OpenSSL Project.
49.\"
50.\" 6. Redistributions of any form whatsoever must retain the following
51.\" acknowledgment:
52.\" "This product includes software developed by the OpenSSL Project
53.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
54.\"
55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
58.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
66.\" OF THE POSSIBILITY OF SUCH DAMAGE.
67.\"
68.Dd $Mdocdate: November 16 2023 $
69.Dt BIO_S_FD 3
70.Os
71.Sh NAME
72.Nm BIO_s_fd ,
73.Nm BIO_set_fd ,
74.Nm BIO_get_fd ,
75.Nm BIO_new_fd ,
76.Nm BIO_fd_non_fatal_error ,
77.Nm BIO_fd_should_retry
78.Nd file descriptor BIO
79.Sh SYNOPSIS
80.In openssl/bio.h
81.Ft const BIO_METHOD *
82.Fo BIO_s_fd
83.Fa "void"
84.Fc
85.Ft long
86.Fo BIO_set_fd
87.Fa "BIO *b"
88.Fa "int fd"
89.Fa "long close_flag"
90.Fc
91.Ft long
92.Fo BIO_get_fd
93.Fa "BIO *b"
94.Fa "int *c"
95.Fc
96.Ft BIO *
97.Fo BIO_new_fd
98.Fa "int fd"
99.Fa "int close_flag"
100.Fc
101.Ft int
102.Fn BIO_fd_non_fatal_error "int errnum"
103.Ft int
104.Fn BIO_fd_should_retry "int retval"
105.Sh DESCRIPTION
106.Fn BIO_s_fd
107returns the file descriptor BIO method.
108This is a wrapper around the platform's file descriptor routines such as
109.Xr read 2
110and
111.Xr write 2 .
112.Pp
113.Xr BIO_read 3
114and
115.Xr BIO_write 3
116read or write the underlying descriptor.
117.Xr BIO_puts 3
118is supported but
119.Xr BIO_gets 3
120is not.
121.Pp
122If the close flag is set,
123.Xr close 2
124is called on the underlying file descriptor when the
125.Vt BIO
126is freed.
127.Pp
128.Xr BIO_reset 3
129attempts to set the file pointer to the start of the file using
130.Fn lseek fd 0 0 .
131.Pp
132.Xr BIO_seek 3
133sets the file pointer to position
134.Fa ofs
135from start of file using
136.Fn lseek fd ofs 0 .
137.Pp
138.Xr BIO_tell 3
139returns the current file position by calling
140.Fn lseek fd 0 1 .
141.Pp
142.Fn BIO_set_fd
143sets the file descriptor of
144.Vt BIO
145.Fa b
146to
147.Fa fd
148and the close flag to
149.Fa close_flag .
150.Pp
151.Fn BIO_get_fd
152places the file descriptor in
153.Fa c
154if it is not
155.Dv NULL
156and also returns the file descriptor.
157.Pp
158.Fn BIO_new_fd
159returns a file descriptor BIO using
160.Fa fd
161and
162.Fa close_flag .
163.Pp
164.Fn BIO_fd_non_fatal_error
165determines whether the error status code
166.Fa errnum
167represents a recoverable error.
168.Fn BIO_fd_should_retry
169determines whether a recoverable error occurred by inspecting both
170.Xr errno 2
171and
172.Fa retval ,
173which is supposed to usually be
174the return value of a previously called function like
175.Xr BIO_read 3
176or
177.Xr BIO_write 3 .
178These two functions are mostly used internally; in application code,
179it is usually easier and more robust to use
180.Xr BIO_should_retry 3 ,
181which works for any BIO type.
182.Pp
183The behaviour of
184.Xr BIO_read 3
185and
186.Xr BIO_write 3
187depends on the behavior of the platform's
188.Xr read 2
189and
190.Xr write 2
191calls on the descriptor.
192If the underlying file descriptor is in a non-blocking mode,
193then the BIO will behave in the manner described in the
194.Xr BIO_read 3
195and
196.Xr BIO_should_retry 3
197manual pages.
198.Pp
199File descriptor BIOs should not be used for socket I/O.
200Use socket BIOs instead.
201.Pp
202.Xr BIO_ctrl 3
203.Fa cmd
204arguments correspond to macros as follows:
205.Bl -column BIO_CTRL_GET_CLOSE BIO_get_close(3) -offset 3n
206.It Fa cmd No constant Ta corresponding macro
207.It Dv BIO_C_FILE_SEEK Ta Xr BIO_seek 3
208.It Dv BIO_C_FILE_TELL Ta Xr BIO_tell 3
209.It Dv BIO_C_GET_FD Ta Fn BIO_get_fd
210.It Dv BIO_C_SET_FD Ta Fn BIO_set_fd
211.It Dv BIO_CTRL_GET_CLOSE Ta Xr BIO_get_close 3
212.It Dv BIO_CTRL_RESET Ta Xr BIO_reset 3
213.It Dv BIO_CTRL_SET_CLOSE Ta Xr BIO_set_close 3
214.El
215.Sh RETURN VALUES
216.Fn BIO_s_fd
217returns the file descriptor BIO method.
218.Pp
219When called on a file descriptor BIO object,
220.Xr BIO_method_type 3
221returns the constant
222.Dv BIO_TYPE_FD
223and
224.Xr BIO_method_name 3
225returns a pointer to the static string
226.Qq file descriptor .
227.Pp
228.Fn BIO_set_fd
229always returns 1.
230.Pp
231.Fn BIO_get_fd
232returns the file descriptor or -1 if the
233.Vt BIO
234has not been initialized.
235.Pp
236.Fn BIO_new_fd
237returns the newly allocated
238.Vt BIO
239or
240.Dv NULL
241if an error occurred.
242.Pp
243.Fn BIO_fd_non_fatal_error
244returns 1 if
245.Fa errnum
246is
247.Dv EAGAIN ,
248.Dv EALREADY ,
249.Dv EINPROGRESS ,
250.Dv EINTR ,
251or
252.Dv ENOTCONN
253and 0 otherwise, even if
254.Fa errnum
255is 0.
256.Pp
257.Fn BIO_fd_should_retry
258returns 1 if
259.Fn BIO_fd_non_fatal_error errno
260is 1 and
261.Fa retval
262is either 0 or \-1, or 0 otherwise.
263.Sh EXAMPLES
264This is a file descriptor BIO version of "Hello World":
265.Bd -literal -offset indent
266BIO *out;
267out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);
268BIO_printf(out, "Hello World\en");
269BIO_free(out);
270.Ed
271.Sh SEE ALSO
272.Xr BIO_new 3 ,
273.Xr BIO_read 3 ,
274.Xr BIO_s_socket 3 ,
275.Xr BIO_seek 3 ,
276.Xr BIO_should_retry 3
277.Sh HISTORY
278.Fn BIO_s_fd ,
279.Fn BIO_set_fd ,
280and
281.Fn BIO_get_fd
282first appeared in SSLeay 0.6.0,
283.Fn BIO_fd_should_retry
284in SSLeay 0.6.5, and
285.Fn BIO_new_fd
286and
287.Fn BIO_fd_non_fatal_error
288in SSLeay 0.8.0.
289All these functions have been available since
290.Ox 2.4 .