secure/lib/libcrypto/man/BIO_new.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "BIO_NEW 3"
 132 .TH BIO_NEW 3 "2018-11-20" "1.1.1a" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 BIO_new, BIO_up_ref, BIO_free, BIO_vfree, BIO_free_all \&\- BIO allocation and freeing functions
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/bio.h>
 143 \&
 144 \& BIO *  BIO_new(const BIO_METHOD *type);
 145 \& int    BIO_up_ref(BIO *a);
 146 \& int    BIO_free(BIO *a);
 147 \& void   BIO_vfree(BIO *a);
 148 \& void   BIO_free_all(BIO *a);
 149 .Ve
 150 .SH "DESCRIPTION"
 151 .IX Header "DESCRIPTION"
 152 The \fIBIO_new()\fR function returns a new \s-1BIO\s0 using method \fBtype\fR.
 153 .PP
 154 \&\fIBIO_up_ref()\fR increments the reference count associated with the \s-1BIO\s0 object.
 155 .PP
 156 \&\fIBIO_free()\fR frees up a single \s-1BIO,\s0 \fIBIO_vfree()\fR also frees up a single \s-1BIO\s0
 157 but it does not return a value.
 158 If \fBa\fR is \s-1NULL\s0 nothing is done.
 159 Calling \fIBIO_free()\fR may also have some effect
 160 on the underlying I/O structure, for example it may close the file being
 161 referred to under certain circumstances. For more details see the individual
 162 \&\s-1BIO_METHOD\s0 descriptions.
 163 .PP
 164 \&\fIBIO_free_all()\fR frees up an entire \s-1BIO\s0 chain, it does not halt if an error
 165 occurs freeing up an individual \s-1BIO\s0 in the chain.
 166 If \fBa\fR is \s-1NULL\s0 nothing is done.
 167 .SH "RETURN VALUES"
 168 .IX Header "RETURN VALUES"
 169 \&\fIBIO_new()\fR returns a newly created \s-1BIO\s0 or \s-1NULL\s0 if the call fails.
 170 .PP
 171 \&\fIBIO_up_ref()\fR and \fIBIO_free()\fR return 1 for success and 0 for failure.
 172 .PP
 173 \&\fIBIO_free_all()\fR and \fIBIO_vfree()\fR do not return values.
 174 .SH "NOTES"
 175 .IX Header "NOTES"
 176 If \fIBIO_free()\fR is called on a \s-1BIO\s0 chain it will only free one \s-1BIO\s0 resulting
 177 in a memory leak.
 178 .PP
 179 Calling \fIBIO_free_all()\fR on a single \s-1BIO\s0 has the same effect as calling \fIBIO_free()\fR
 180 on it other than the discarded return value.
 181 .SH "HISTORY"
 182 .IX Header "HISTORY"
 183 \&\fIBIO_set()\fR was removed in OpenSSL 1.1.0 as \s-1BIO\s0 type is now opaque.
 184 .SH "EXAMPLE"
 185 .IX Header "EXAMPLE"
 186 Create a memory \s-1BIO:\s0
 187 .PP
 188 .Vb 1
 189 \& BIO *mem = BIO_new(BIO_s_mem());
 190 .Ve
 191 .SH "COPYRIGHT"
 192 .IX Header "COPYRIGHT"
 193 Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
 194 .PP
 195 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 196 this file except in compliance with the License.  You can obtain a copy
 197 in the file \s-1LICENSE\s0 in the source distribution or at
 198 <https://www.openssl.org/source/license.html>.