f4401cd869
alter des.h to be friendly with openssl/des.h (you can include both in the same file) make libkrb to depend on libdes. bump major. massage various portioin of heimdal to be friendly with openssl 0.9.7b.
291 lines
8.8 KiB
Groff
291 lines
8.8 KiB
Groff
.\" $NetBSD: BIO_s_file.3,v 1.8 2003/07/24 14:16:36 itojun Exp $
|
|
.\"
|
|
.\" Automatically generated by Pod::Man version 1.02
|
|
.\" Thu Jul 24 13:07:50 2003
|
|
.\"
|
|
.\" Standard preamble:
|
|
.\" ======================================================================
|
|
.de Sh \" Subsection heading
|
|
.br
|
|
.if t .Sp
|
|
.ne 5
|
|
.PP
|
|
\fB\\$1\fR
|
|
.PP
|
|
..
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.de Ip \" List item
|
|
.br
|
|
.ie \\n(.$>=3 .ne \\$3
|
|
.el .ne 3
|
|
.IP "\\$1" \\$2
|
|
..
|
|
.de Vb \" Begin verbatim text
|
|
.ft CW
|
|
.nf
|
|
.ne \\$1
|
|
..
|
|
.de Ve \" End verbatim text
|
|
.ft R
|
|
|
|
.fi
|
|
..
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
|
.\" double quote, and \*(R" will give a right double quote. | will give a
|
|
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used
|
|
.\" to do unbreakable dashes and therefore won't be available. \*(C` and
|
|
.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
|
|
.tr \(*W-|\(bv\*(Tr
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
|
.ie n \{\
|
|
. ds -- \(*W-
|
|
. ds PI pi
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
|
. ds L" ""
|
|
. ds R" ""
|
|
. ds C` `
|
|
. ds C' '
|
|
'br\}
|
|
.el\{\
|
|
. ds -- \|\(em\|
|
|
. ds PI \(*p
|
|
. ds L" ``
|
|
. ds R" ''
|
|
'br\}
|
|
.\"
|
|
.\" If the F register is turned on, we'll generate index entries on stderr
|
|
.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
|
|
.\" index entries marked with X<> in POD. Of course, you'll have to process
|
|
.\" the output yourself in some meaningful fashion.
|
|
.if \nF \{\
|
|
. de IX
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
|
. .
|
|
. nr % 0
|
|
. rr F
|
|
.\}
|
|
.\"
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it
|
|
.\" makes way too many mistakes in technical documents.
|
|
.hy 0
|
|
.if n .na
|
|
.\"
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
|
.bd B 3
|
|
. \" fudge factors for nroff and troff
|
|
.if n \{\
|
|
. ds #H 0
|
|
. ds #V .8m
|
|
. ds #F .3m
|
|
. ds #[ \f1
|
|
. ds #] \fP
|
|
.\}
|
|
.if t \{\
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
|
. ds #V .6m
|
|
. ds #F 0
|
|
. ds #[ \&
|
|
. ds #] \&
|
|
.\}
|
|
. \" simple accents for nroff and troff
|
|
.if n \{\
|
|
. ds ' \&
|
|
. ds ` \&
|
|
. ds ^ \&
|
|
. ds , \&
|
|
. ds ~ ~
|
|
. ds /
|
|
.\}
|
|
.if t \{\
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
|
.\}
|
|
. \" troff and (daisy-wheel) nroff accents
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
|
. \" corrections for vroff
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
|
. \" for low resolution devices (crt and lpr)
|
|
.if \n(.H>23 .if \n(.V>19 \
|
|
\{\
|
|
. ds : e
|
|
. ds 8 ss
|
|
. ds o a
|
|
. ds d- d\h'-1'\(ga
|
|
. ds D- D\h'-1'\(hy
|
|
. ds th \o'bp'
|
|
. ds Th \o'LP'
|
|
. ds ae ae
|
|
. ds Ae AE
|
|
.\}
|
|
.rm #[ #] #H #V #F C
|
|
.\" ======================================================================
|
|
.\"
|
|
.IX Title "BIO_s_file 3"
|
|
.TH BIO_s_file 3 "0.9.7b" "2000-09-19" "OpenSSL"
|
|
.UC
|
|
.SH "NAME"
|
|
BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp,
|
|
BIO_read_filename, BIO_write_filename, BIO_append_filename,
|
|
BIO_rw_filename \- \s-1FILE\s0 bio
|
|
.SH "LIBRARY"
|
|
libcrypto, -lcrypto
|
|
.SH "SYNOPSIS"
|
|
.IX Header "SYNOPSIS"
|
|
.Vb 1
|
|
\& #include <openssl/bio.h>
|
|
.Ve
|
|
.Vb 3
|
|
\& BIO_METHOD * BIO_s_file(void);
|
|
\& BIO *BIO_new_file(const char *filename, const char *mode);
|
|
\& BIO *BIO_new_fp(FILE *stream, int flags);
|
|
.Ve
|
|
.Vb 2
|
|
\& BIO_set_fp(BIO *b,FILE *fp, int flags);
|
|
\& BIO_get_fp(BIO *b,FILE **fpp);
|
|
.Ve
|
|
.Vb 4
|
|
\& int BIO_read_filename(BIO *b, char *name)
|
|
\& int BIO_write_filename(BIO *b, char *name)
|
|
\& int BIO_append_filename(BIO *b, char *name)
|
|
\& int BIO_rw_filename(BIO *b, char *name)
|
|
.Ve
|
|
.SH "DESCRIPTION"
|
|
.IX Header "DESCRIPTION"
|
|
\&\fIBIO_s_file()\fR returns the \s-1BIO\s0 file method. As its name implies it
|
|
is a wrapper round the stdio \s-1FILE\s0 structure and it is a
|
|
source/sink \s-1BIO\s0.
|
|
.PP
|
|
Calls to \fIBIO_read()\fR and \fIBIO_write()\fR read and write data to the
|
|
underlying stream. \fIBIO_gets()\fR and \fIBIO_puts()\fR are supported on file BIOs.
|
|
.PP
|
|
\&\fIBIO_flush()\fR on a file \s-1BIO\s0 calls the \fIfflush()\fR function on the wrapped
|
|
stream.
|
|
.PP
|
|
\&\fIBIO_reset()\fR attempts to change the file pointer to the start of file
|
|
using fseek(stream, 0, 0).
|
|
.PP
|
|
\&\fIBIO_seek()\fR sets the file pointer to position \fBofs\fR from start of file
|
|
using fseek(stream, ofs, 0).
|
|
.PP
|
|
\&\fIBIO_eof()\fR calls \fIfeof()\fR.
|
|
.PP
|
|
Setting the \s-1BIO_CLOSE\s0 flag calls \fIfclose()\fR on the stream when the \s-1BIO\s0
|
|
is freed.
|
|
.PP
|
|
\&\fIBIO_new_file()\fR creates a new file \s-1BIO\s0 with mode \fBmode\fR the meaning
|
|
of \fBmode\fR is the same as the stdio function \fIfopen()\fR. The \s-1BIO_CLOSE\s0
|
|
flag is set on the returned \s-1BIO\s0.
|
|
.PP
|
|
\&\fIBIO_new_fp()\fR creates a file \s-1BIO\s0 wrapping \fBstream\fR. Flags can be:
|
|
\&\s-1BIO_CLOSE\s0, \s-1BIO_NOCLOSE\s0 (the close flag) \s-1BIO_FP_TEXT\s0 (sets the underlying
|
|
stream to text mode, default is binary: this only has any effect under
|
|
Win32).
|
|
.PP
|
|
\&\fIBIO_set_fp()\fR set the fp of a file \s-1BIO\s0 to \fBfp\fR. \fBflags\fR has the same
|
|
meaning as in \fIBIO_new_fp()\fR, it is a macro.
|
|
.PP
|
|
\&\fIBIO_get_fp()\fR retrieves the fp of a file \s-1BIO\s0, it is a macro.
|
|
.PP
|
|
\&\fIBIO_seek()\fR is a macro that sets the position pointer to \fBoffset\fR bytes
|
|
from the start of file.
|
|
.PP
|
|
\&\fIBIO_tell()\fR returns the value of the position pointer.
|
|
.PP
|
|
\&\fIBIO_read_filename()\fR, \fIBIO_write_filename()\fR, \fIBIO_append_filename()\fR and
|
|
\&\fIBIO_rw_filename()\fR set the file \s-1BIO\s0 \fBb\fR to use file \fBname\fR for
|
|
reading, writing, append or read write respectively.
|
|
.SH "NOTES"
|
|
.IX Header "NOTES"
|
|
When wrapping stdout, stdin or stderr the underlying stream should not
|
|
normally be closed so the \s-1BIO_NOCLOSE\s0 flag should be set.
|
|
.PP
|
|
Because the file \s-1BIO\s0 calls the underlying stdio functions any quirks
|
|
in stdio behaviour will be mirrored by the corresponding \s-1BIO\s0.
|
|
.SH "EXAMPLES"
|
|
.IX Header "EXAMPLES"
|
|
File \s-1BIO\s0 \*(L"hello world\*(R":
|
|
.PP
|
|
.Vb 3
|
|
\& BIO *bio_out;
|
|
\& bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
|
|
\& BIO_printf(bio_out, "Hello World\en");
|
|
.Ve
|
|
Alternative technique:
|
|
.PP
|
|
.Vb 5
|
|
\& BIO *bio_out;
|
|
\& bio_out = BIO_new(BIO_s_file());
|
|
\& if(bio_out == NULL) /* Error ... */
|
|
\& if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */
|
|
\& BIO_printf(bio_out, "Hello World\en");
|
|
.Ve
|
|
Write to a file:
|
|
.PP
|
|
.Vb 5
|
|
\& BIO *out;
|
|
\& out = BIO_new_file("filename.txt", "w");
|
|
\& if(!out) /* Error occurred */
|
|
\& BIO_printf(out, "Hello World\en");
|
|
\& BIO_free(out);
|
|
.Ve
|
|
Alternative technique:
|
|
.PP
|
|
.Vb 6
|
|
\& BIO *out;
|
|
\& out = BIO_new(BIO_s_file());
|
|
\& if(out == NULL) /* Error ... */
|
|
\& if(!BIO_write_filename(out, "filename.txt")) /* Error ... */
|
|
\& BIO_printf(out, "Hello World\en");
|
|
\& BIO_free(out);
|
|
.Ve
|
|
.SH "RETURN VALUES"
|
|
.IX Header "RETURN VALUES"
|
|
\&\fIBIO_s_file()\fR returns the file \s-1BIO\s0 method.
|
|
.PP
|
|
\&\fIBIO_new_file()\fR and \fIBIO_new_fp()\fR return a file \s-1BIO\s0 or \s-1NULL\s0 if an error
|
|
occurred.
|
|
.PP
|
|
\&\fIBIO_set_fp()\fR and \fIBIO_get_fp()\fR return 1 for success or 0 for failure
|
|
(although the current implementation never return 0).
|
|
.PP
|
|
\&\fIBIO_seek()\fR returns the same value as the underlying \fIfseek()\fR function:
|
|
0 for success or \-1 for failure.
|
|
.PP
|
|
\&\fIBIO_tell()\fR returns the current file position.
|
|
.PP
|
|
\&\fIBIO_read_filename()\fR, \fIBIO_write_filename()\fR, \fIBIO_append_filename()\fR and
|
|
\&\fIBIO_rw_filename()\fR return 1 for success or 0 for failure.
|
|
.SH "BUGS"
|
|
.IX Header "BUGS"
|
|
\&\fIBIO_reset()\fR and \fIBIO_seek()\fR are implemented using \fIfseek()\fR on the underlying
|
|
stream. The return value for \fIfseek()\fR is 0 for success or \-1 if an error
|
|
occurred this differs from other types of \s-1BIO\s0 which will typically return
|
|
1 for success and a non positive value if an error occurred.
|
|
.SH "SEE ALSO"
|
|
.IX Header "SEE ALSO"
|
|
BIO_seek(3), BIO_tell(3),
|
|
BIO_reset(3), BIO_flush(3),
|
|
BIO_read(3),
|
|
BIO_write(3), BIO_puts(3),
|
|
BIO_gets(3), BIO_printf(3),
|
|
BIO_set_close(3), BIO_get_close(3)
|