2
0

BIO_s_file.pod 4.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144
  1. =pod
  2. =head1 NAME
  3. BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp,
  4. BIO_read_filename, BIO_write_filename, BIO_append_filename,
  5. BIO_rw_filename - FILE bio
  6. =head1 SYNOPSIS
  7. #include <openssl/bio.h>
  8. BIO_METHOD * BIO_s_file(void);
  9. BIO *BIO_new_file(const char *filename, const char *mode);
  10. BIO *BIO_new_fp(FILE *stream, int flags);
  11. BIO_set_fp(BIO *b,FILE *fp, int flags);
  12. BIO_get_fp(BIO *b,FILE **fpp);
  13. int BIO_read_filename(BIO *b, char *name)
  14. int BIO_write_filename(BIO *b, char *name)
  15. int BIO_append_filename(BIO *b, char *name)
  16. int BIO_rw_filename(BIO *b, char *name)
  17. =head1 DESCRIPTION
  18. BIO_s_file() returns the BIO file method. As its name implies it
  19. is a wrapper round the stdio FILE structure and it is a
  20. source/sink BIO.
  21. Calls to BIO_read() and BIO_write() read and write data to the
  22. underlying stream. BIO_gets() and BIO_puts() are supported on file BIOs.
  23. BIO_flush() on a file BIO calls the fflush() function on the wrapped
  24. stream.
  25. BIO_reset() attempts to change the file pointer to the start of file
  26. using fseek(stream, 0, 0).
  27. BIO_seek() sets the file pointer to position B<ofs> from start of file
  28. using fseek(stream, ofs, 0).
  29. BIO_eof() calls feof().
  30. Setting the BIO_CLOSE flag calls fclose() on the stream when the BIO
  31. is freed.
  32. BIO_new_file() creates a new file BIO with mode B<mode> the meaning
  33. of B<mode> is the same as the stdio function fopen(). The BIO_CLOSE
  34. flag is set on the returned BIO.
  35. BIO_new_fp() creates a file BIO wrapping B<stream>. Flags can be:
  36. BIO_CLOSE, BIO_NOCLOSE (the close flag) BIO_FP_TEXT (sets the underlying
  37. stream to text mode, default is binary: this only has any effect under
  38. Win32).
  39. BIO_set_fp() set the fp of a file BIO to B<fp>. B<flags> has the same
  40. meaning as in BIO_new_fp(), it is a macro.
  41. BIO_get_fp() retrieves the fp of a file BIO, it is a macro.
  42. BIO_seek() is a macro that sets the position pointer to B<offset> bytes
  43. from the start of file.
  44. BIO_tell() returns the value of the position pointer.
  45. BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
  46. BIO_rw_filename() set the file BIO B<b> to use file B<name> for
  47. reading, writing, append or read write respectively.
  48. =head1 NOTES
  49. When wrapping stdout, stdin or stderr the underlying stream should not
  50. normally be closed so the BIO_NOCLOSE flag should be set.
  51. Because the file BIO calls the underlying stdio functions any quirks
  52. in stdio behaviour will be mirrored by the corresponding BIO.
  53. =head1 EXAMPLES
  54. File BIO "hello world":
  55. BIO *bio_out;
  56. bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
  57. BIO_printf(bio_out, "Hello World\n");
  58. Alternative technique:
  59. BIO *bio_out;
  60. bio_out = BIO_new(BIO_s_file());
  61. if(bio_out == NULL) /* Error ... */
  62. if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */
  63. BIO_printf(bio_out, "Hello World\n");
  64. Write to a file:
  65. BIO *out;
  66. out = BIO_new_file("filename.txt", "w");
  67. if(!out) /* Error occurred */
  68. BIO_printf(out, "Hello World\n");
  69. BIO_free(out);
  70. Alternative technique:
  71. BIO *out;
  72. out = BIO_new(BIO_s_file());
  73. if(out == NULL) /* Error ... */
  74. if(!BIO_write_filename(out, "filename.txt")) /* Error ... */
  75. BIO_printf(out, "Hello World\n");
  76. BIO_free(out);
  77. =head1 RETURN VALUES
  78. BIO_s_file() returns the file BIO method.
  79. BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error
  80. occurred.
  81. BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure
  82. (although the current implementation never return 0).
  83. BIO_seek() returns the same value as the underlying fseek() function:
  84. 0 for success or -1 for failure.
  85. BIO_tell() returns the current file position.
  86. BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
  87. BIO_rw_filename() return 1 for success or 0 for failure.
  88. =head1 BUGS
  89. BIO_reset() and BIO_seek() are implemented using fseek() on the underlying
  90. stream. The return value for fseek() is 0 for success or -1 if an error
  91. occurred this differs from other types of BIO which will typically return
  92. 1 for success and a non positive value if an error occurred.
  93. =head1 SEE ALSO
  94. L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>,
  95. L<BIO_reset(3)|BIO_reset(3)>, L<BIO_flush(3)|BIO_flush(3)>,
  96. L<BIO_read(3)|BIO_read(3)>,
  97. L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>,
  98. L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>,
  99. L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)>