aa7ba363adb2b3c2c654bd77c60ebc195a2fd0ea
[openssl.git] / doc / crypto / BIO_s_fd.pod
1 =pod
2
3 =head1 NAME
4
5 BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO
6
7 =head1 SYNOPSIS
8
9  #include <openssl/bio.h>
10
11  const BIO_METHOD *BIO_s_fd(void);
12
13  int BIO_set_fd(BIO *b, int fd, int c);
14  int BIO_get_fd(BIO *b, int *c);
15
16  BIO *BIO_new_fd(int fd, int close_flag);
17
18 =head1 DESCRIPTION
19
20 BIO_s_fd() returns the file descriptor BIO method. This is a wrapper
21 round the platforms file descriptor routines such as read() and write().
22
23 BIO_read() and BIO_write() read or write the underlying descriptor.
24 BIO_puts() is supported but BIO_gets() is not.
25
26 If the close flag is set then close() is called on the underlying
27 file descriptor when the BIO is freed.
28
29 BIO_reset() attempts to change the file pointer to the start of file
30 such as by using B<lseek(fd, 0, 0)>.
31
32 BIO_seek() sets the file pointer to position B<ofs> from start of file
33 such as by using B<lseek(fd, ofs, 0)>.
34
35 BIO_tell() returns the current file position such as by calling
36 B<lseek(fd, 0, 1)>.
37
38 BIO_set_fd() sets the file descriptor of BIO B<b> to B<fd> and the close
39 flag to B<c>.
40
41 BIO_get_fd() places the file descriptor in B<c> if it is not NULL, it also
42 returns the file descriptor.
43
44 BIO_new_fd() returns a file descriptor BIO using B<fd> and B<close_flag>.
45
46 =head1 NOTES
47
48 The behaviour of BIO_read() and BIO_write() depends on the behavior of the
49 platforms read() and write() calls on the descriptor. If the underlying
50 file descriptor is in a non blocking mode then the BIO will behave in the
51 manner described in the L<BIO_read(3)> and L<BIO_should_retry(3)>
52 manual pages.
53
54 File descriptor BIOs should not be used for socket I/O. Use socket BIOs
55 instead.
56
57 BIO_set_fd() and BIO_get_fd() are implemented as macros.
58
59 =head1 RETURN VALUES
60
61 BIO_s_fd() returns the file descriptor BIO method.
62
63 BIO_set_fd() always returns 1.
64
65 BIO_get_fd() returns the file descriptor or -1 if the BIO has not
66 been initialized.
67
68 BIO_new_fd() returns the newly allocated BIO or NULL is an error
69 occurred.
70
71 =head1 EXAMPLE
72
73 This is a file descriptor BIO version of "Hello World":
74
75  BIO *out;
76  
77  out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);
78  BIO_printf(out, "Hello World\n");
79  BIO_free(out);
80
81 =head1 SEE ALSO
82
83 L<BIO_seek(3)>, L<BIO_tell(3)>,
84 L<BIO_reset(3)>, L<BIO_read(3)>,
85 L<BIO_write(3)>, L<BIO_puts(3)>,
86 L<BIO_gets(3)>, L<BIO_printf(3)>,
87 L<BIO_set_close(3)>, L<BIO_get_close(3)>
88
89 =head1 COPYRIGHT
90
91 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
92
93 Licensed under the OpenSSL license (the "License").  You may not use
94 this file except in compliance with the License.  You can obtain a copy
95 in the file LICENSE in the source distribution or at
96 L<https://www.openssl.org/source/license.html>.
97
98 =cut