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  #define BIO_set_fd(b,fd,c)     BIO_int_ctrl(b,BIO_C_SET_FD,c,fd)
  14  #define BIO_get_fd(b,c)        BIO_ctrl(b,BIO_C_GET_FD,0,(char *)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 using lseek(fd, 0, 0).
  31
  32 BIO_seek() sets the file pointer to position B<ofs> from start of file
  33 using lseek(fd, ofs, 0).
  34
  35 BIO_tell() returns the current file position by calling lseek(fd, 0, 1).
  36
  37 BIO_set_fd() sets the file descriptor of BIO B<b> to B<fd> and the close
  38 flag to B<c>.
  39
  40 BIO_get_fd() places the file descriptor in B<c> if it is not NULL, it also
  41 returns the file descriptor. If B<c> is not NULL it should be of type
  42 (int *).
  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 =head1 RETURN VALUES
  58
  59 BIO_s_fd() returns the file descriptor BIO method.
  60
  61 BIO_reset() returns zero for success and -1 if an error occurred.
  62 BIO_seek() and BIO_tell() return the current file position or -1
  63 is an error occurred. These values reflect the underlying lseek()
  64 behaviour.
  65
  66 BIO_set_fd() always returns 1.
  67
  68 BIO_get_fd() returns the file descriptor or -1 if the BIO has not
  69 been initialized.
  70
  71 BIO_new_fd() returns the newly allocated BIO or NULL is an error
  72 occurred.
  73
  74 =head1 EXAMPLE
  75
  76 This is a file descriptor BIO version of "Hello World":
  77
  78  BIO *out;
  79  out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);
  80  BIO_printf(out, "Hello World\n");
  81  BIO_free(out);
  82
  83 =head1 SEE ALSO
  84
  85 L<BIO_seek(3)>, L<BIO_tell(3)>,
  86 L<BIO_reset(3)>, L<BIO_read(3)>,
  87 L<BIO_write(3)>, L<BIO_puts(3)>,
  88 L<BIO_gets(3)>, L<BIO_printf(3)>,
  89 L<BIO_set_close(3)>, L<BIO_get_close(3)>
  90
  91 =cut
  92
  93 =head1 COPYRIGHT
  94
  95 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
  96
  97 Licensed under the OpenSSL license (the "License").  You may not use
  98 this file except in compliance with the License.  You can obtain a copy
  99 in the file LICENSE in the source distribution or at
 100 L<https://www.openssl.org/source/license.html>.
 101
 102 =cut