doc/man3/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_ex() and BIO_write_ex() 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_ex() and BIO_write_ex() 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_ex(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_ex(3)>,
  85 L<BIO_write_ex(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 Apache License 2.0 (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