secure/lib/libcrypto/man/BIO_push.3

   1 .\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  31 .\" nothing in troff, for use with C<>.
  32 .tr \(*W-
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" Escape single quotes in literal strings from groff's Unicode transform.
  52 .ie \n(.g .ds Aq \(aq
  53 .el       .ds Aq '
  54 .\"
  55 .\" If the F register is turned on, we'll generate index entries on stderr for
  56 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  57 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  58 .\" output yourself in some meaningful fashion.
  59 .ie \nF \{\
  60 .    de IX
  61 .    tm Index:\\$1\t\\n%\t"\\$2"
  62 ..
  63 .    nr % 0
  64 .    rr F
  65 .\}
  66 .el \{\
  67 .    de IX
  68 ..
  69 .\}
  70 .\"
  71 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  72 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  73 .    \" fudge factors for nroff and troff
  74 .if n \{\
  75 .    ds #H 0
  76 .    ds #V .8m
  77 .    ds #F .3m
  78 .    ds #[ \f1
  79 .    ds #] \fP
  80 .\}
  81 .if t \{\
  82 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  83 .    ds #V .6m
  84 .    ds #F 0
  85 .    ds #[ \&
  86 .    ds #] \&
  87 .\}
  88 .    \" simple accents for nroff and troff
  89 .if n \{\
  90 .    ds ' \&
  91 .    ds ` \&
  92 .    ds ^ \&
  93 .    ds , \&
  94 .    ds ~ ~
  95 .    ds /
  96 .\}
  97 .if t \{\
  98 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  99 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 100 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 101 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 102 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 103 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 104 .\}
 105 .    \" troff and (daisy-wheel) nroff accents
 106 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 107 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 108 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 109 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 110 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 111 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 112 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 113 .ds ae a\h'-(\w'a'u*4/10)'e
 114 .ds Ae A\h'-(\w'A'u*4/10)'E
 115 .    \" corrections for vroff
 116 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 117 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 118 .    \" for low resolution devices (crt and lpr)
 119 .if \n(.H>23 .if \n(.V>19 \
 120 \{\
 121 .    ds : e
 122 .    ds 8 ss
 123 .    ds o a
 124 .    ds d- d\h'-1'\(ga
 125 .    ds D- D\h'-1'\(hy
 126 .    ds th \o'bp'
 127 .    ds Th \o'LP'
 128 .    ds ae ae
 129 .    ds Ae AE
 130 .\}
 131 .rm #[ #] #H #V #F C
 132 .\" ========================================================================
 133 .\"
 134 .IX Title "BIO_push 3"
 135 .TH BIO_push 3 "2009-11-06" "0.9.8l" "OpenSSL"
 136 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 137 .\" way too many mistakes in technical documents.
 138 .if n .ad l
 139 .nh
 140 .SH "NAME"
 141 BIO_push, BIO_pop \- add and remove BIOs from a chain.
 142 .SH "SYNOPSIS"
 143 .IX Header "SYNOPSIS"
 144 .Vb 1
 145 \& #include <openssl/bio.h>
 146 \&
 147 \& BIO *  BIO_push(BIO *b,BIO *append);
 148 \& BIO *  BIO_pop(BIO *b);
 149 .Ve
 150 .SH "DESCRIPTION"
 151 .IX Header "DESCRIPTION"
 152 The \fIBIO_push()\fR function appends the \s-1BIO\s0 \fBappend\fR to \fBb\fR, it returns
 153 \&\fBb\fR.
 154 .PP
 155 \&\fIBIO_pop()\fR removes the \s-1BIO\s0 \fBb\fR from a chain and returns the next \s-1BIO\s0
 156 in the chain, or \s-1NULL\s0 if there is no next \s-1BIO\s0. The removed \s-1BIO\s0 then
 157 becomes a single \s-1BIO\s0 with no association with the original chain,
 158 it can thus be freed or attached to a different chain.
 159 .SH "NOTES"
 160 .IX Header "NOTES"
 161 The names of these functions are perhaps a little misleading. \fIBIO_push()\fR
 162 joins two \s-1BIO\s0 chains whereas \fIBIO_pop()\fR deletes a single \s-1BIO\s0 from a chain,
 163 the deleted \s-1BIO\s0 does not need to be at the end of a chain.
 164 .PP
 165 The process of calling \fIBIO_push()\fR and \fIBIO_pop()\fR on a \s-1BIO\s0 may have additional
 166 consequences (a control call is made to the affected BIOs) any effects will
 167 be noted in the descriptions of individual BIOs.
 168 .SH "EXAMPLES"
 169 .IX Header "EXAMPLES"
 170 For these examples suppose \fBmd1\fR and \fBmd2\fR are digest BIOs, \fBb64\fR is
 171 a base64 \s-1BIO\s0 and \fBf\fR is a file \s-1BIO\s0.
 172 .PP
 173 If the call:
 174 .PP
 175 .Vb 1
 176 \& BIO_push(b64, f);
 177 .Ve
 178 .PP
 179 is made then the new chain will be \fBb64\-chain\fR. After making the calls
 180 .PP
 181 .Vb 2
 182 \& BIO_push(md2, b64);
 183 \& BIO_push(md1, md2);
 184 .Ve
 185 .PP
 186 the new chain is \fBmd1\-md2\-b64\-f\fR. Data written to \fBmd1\fR will be digested
 187 by \fBmd1\fR and \fBmd2\fR, \fBbase64\fR encoded and written to \fBf\fR.
 188 .PP
 189 It should be noted that reading causes data to pass in the reverse
 190 direction, that is data is read from \fBf\fR, base64 \fBdecoded\fR and digested
 191 by \fBmd1\fR and \fBmd2\fR. If the call:
 192 .PP
 193 .Vb 1
 194 \& BIO_pop(md2);
 195 .Ve
 196 .PP
 197 The call will return \fBb64\fR and the new chain will be \fBmd1\-b64\-f\fR data can
 198 be written to \fBmd1\fR as before.
 199 .SH "RETURN VALUES"
 200 .IX Header "RETURN VALUES"
 201 \&\fIBIO_push()\fR returns the end of the chain, \fBb\fR.
 202 .PP
 203 \&\fIBIO_pop()\fR returns the next \s-1BIO\s0 in the chain, or \s-1NULL\s0 if there is no next
 204 \&\s-1BIO\s0.
 205 .SH "SEE ALSO"
 206 .IX Header "SEE ALSO"
 207 \&\s-1TBA\s0