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.
261 lines
8.3 KiB
Groff
261 lines
8.3 KiB
Groff
.\" $NetBSD: BIO_s_mem.3,v 1.9 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_mem 3"
|
|
.TH BIO_s_mem 3 "0.9.7b" "2000-09-17" "OpenSSL"
|
|
.UC
|
|
.SH "NAME"
|
|
BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf,
|
|
BIO_get_mem_ptr, BIO_new_mem_buf \- memory \s-1BIO\s0
|
|
.SH "LIBRARY"
|
|
libcrypto, -lcrypto
|
|
.SH "SYNOPSIS"
|
|
.IX Header "SYNOPSIS"
|
|
.Vb 1
|
|
\& #include <openssl/bio.h>
|
|
.Ve
|
|
.Vb 1
|
|
\& BIO_METHOD * BIO_s_mem(void);
|
|
.Ve
|
|
.Vb 4
|
|
\& BIO_set_mem_eof_return(BIO *b,int v)
|
|
\& long BIO_get_mem_data(BIO *b, char **pp)
|
|
\& BIO_set_mem_buf(BIO *b,BUF_MEM *bm,int c)
|
|
\& BIO_get_mem_ptr(BIO *b,BUF_MEM **pp)
|
|
.Ve
|
|
.Vb 1
|
|
\& BIO *BIO_new_mem_buf(void *buf, int len);
|
|
.Ve
|
|
.SH "DESCRIPTION"
|
|
.IX Header "DESCRIPTION"
|
|
\&\fIBIO_s_mem()\fR return the memory \s-1BIO\s0 method function.
|
|
.PP
|
|
A memory \s-1BIO\s0 is a source/sink \s-1BIO\s0 which uses memory for its I/O. Data
|
|
written to a memory \s-1BIO\s0 is stored in a \s-1BUF_MEM\s0 structure which is extended
|
|
as appropriate to accommodate the stored data.
|
|
.PP
|
|
Any data written to a memory \s-1BIO\s0 can be recalled by reading from it.
|
|
Unless the memory \s-1BIO\s0 is read only any data read from it is deleted from
|
|
the \s-1BIO\s0.
|
|
.PP
|
|
Memory BIOs support \fIBIO_gets()\fR and \fIBIO_puts()\fR.
|
|
.PP
|
|
If the \s-1BIO_CLOSE\s0 flag is set when a memory \s-1BIO\s0 is freed then the underlying
|
|
\&\s-1BUF_MEM\s0 structure is also freed.
|
|
.PP
|
|
Calling \fIBIO_reset()\fR on a read write memory \s-1BIO\s0 clears any data in it. On a
|
|
read only \s-1BIO\s0 it restores the \s-1BIO\s0 to its original state and the read only
|
|
data can be read again.
|
|
.PP
|
|
\&\fIBIO_eof()\fR is true if no data is in the \s-1BIO\s0.
|
|
.PP
|
|
\&\fIBIO_ctrl_pending()\fR returns the number of bytes currently stored.
|
|
.PP
|
|
\&\fIBIO_set_mem_eof_return()\fR sets the behaviour of memory \s-1BIO\s0 \fBb\fR when it is
|
|
empty. If the \fBv\fR is zero then an empty memory \s-1BIO\s0 will return \s-1EOF\s0 (that is
|
|
it will return zero and \fIBIO_should_retry\fR\|(b) will be false. If \fBv\fR is non
|
|
zero then it will return \fBv\fR when it is empty and it will set the read retry
|
|
flag (that is \fIBIO_read_retry\fR\|(b) is true). To avoid ambiguity with a normal
|
|
positive return value \fBv\fR should be set to a negative value, typically \-1.
|
|
.PP
|
|
\&\fIBIO_get_mem_data()\fR sets \fBpp\fR to a pointer to the start of the memory BIOs data
|
|
and returns the total amount of data available. It is implemented as a macro.
|
|
.PP
|
|
\&\fIBIO_set_mem_buf()\fR sets the internal \s-1BUF_MEM\s0 structure to \fBbm\fR and sets the
|
|
close flag to \fBc\fR, that is \fBc\fR should be either \s-1BIO_CLOSE\s0 or \s-1BIO_NOCLOSE\s0.
|
|
It is a macro.
|
|
.PP
|
|
\&\fIBIO_get_mem_ptr()\fR places the underlying \s-1BUF_MEM\s0 structure in \fBpp\fR. It is
|
|
a macro.
|
|
.PP
|
|
\&\fIBIO_new_mem_buf()\fR creates a memory \s-1BIO\s0 using \fBlen\fR bytes of data at \fBbuf\fR,
|
|
if \fBlen\fR is \-1 then the \fBbuf\fR is assumed to be null terminated and its
|
|
length is determined by \fBstrlen\fR. The \s-1BIO\s0 is set to a read only state and
|
|
as a result cannot be written to. This is useful when some data needs to be
|
|
made available from a static area of memory in the form of a \s-1BIO\s0. The
|
|
supplied data is read directly from the supplied buffer: it is \fBnot\fR copied
|
|
first, so the supplied area of memory must be unchanged until the \s-1BIO\s0 is freed.
|
|
.SH "NOTES"
|
|
.IX Header "NOTES"
|
|
Writes to memory BIOs will always succeed if memory is available: that is
|
|
their size can grow indefinitely.
|
|
.PP
|
|
Every read from a read write memory \s-1BIO\s0 will remove the data just read with
|
|
an internal copy operation, if a \s-1BIO\s0 contains a lots of data and it is
|
|
read in small chunks the operation can be very slow. The use of a read only
|
|
memory \s-1BIO\s0 avoids this problem. If the \s-1BIO\s0 must be read write then adding
|
|
a buffering \s-1BIO\s0 to the chain will speed up the process.
|
|
.SH "BUGS"
|
|
.IX Header "BUGS"
|
|
There should be an option to set the maximum size of a memory \s-1BIO\s0.
|
|
.PP
|
|
There should be a way to \*(L"rewind\*(R" a read write \s-1BIO\s0 without destroying
|
|
its contents.
|
|
.PP
|
|
The copying operation should not occur after every small read of a large \s-1BIO\s0
|
|
to improve efficiency.
|
|
.SH "EXAMPLE"
|
|
.IX Header "EXAMPLE"
|
|
Create a memory \s-1BIO\s0 and write some data to it:
|
|
.PP
|
|
.Vb 2
|
|
\& BIO *mem = BIO_new(BIO_s_mem());
|
|
\& BIO_puts(mem, "Hello World\en");
|
|
.Ve
|
|
Create a read only memory \s-1BIO:\s0
|
|
.PP
|
|
.Vb 3
|
|
\& char data[] = "Hello World";
|
|
\& BIO *mem;
|
|
\& mem = BIO_new_mem_buf(data, -1);
|
|
.Ve
|
|
Extract the \s-1BUF_MEM\s0 structure from a memory \s-1BIO\s0 and then free up the \s-1BIO:\s0
|
|
.PP
|
|
.Vb 4
|
|
\& BUF_MEM *bptr;
|
|
\& BIO_get_mem_ptr(mem, &bptr);
|
|
\& BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
|
|
\& BIO_free(mem);
|
|
.Ve
|
|
.SH "SEE ALSO"
|
|
.IX Header "SEE ALSO"
|
|
\&\s-1TBA\s0
|