secure/lib/libcrypto/man/man3/BIO_ADDR.3

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.40)
   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 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "BIO_ADDR 3"
 136 .TH BIO_ADDR 3 "2020-04-21" "1.1.1g" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 BIO_ADDR, BIO_ADDR_new, BIO_ADDR_clear, BIO_ADDR_free, BIO_ADDR_rawmake, BIO_ADDR_family, BIO_ADDR_rawaddress, BIO_ADDR_rawport, BIO_ADDR_hostname_string, BIO_ADDR_service_string, BIO_ADDR_path_string \- BIO_ADDR routines
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 2
 146 \& #include <sys/types.h>
 147 \& #include <openssl/bio.h>
 148 \&
 149 \& typedef union bio_addr_st BIO_ADDR;
 150 \&
 151 \& BIO_ADDR *BIO_ADDR_new(void);
 152 \& void BIO_ADDR_free(BIO_ADDR *);
 153 \& void BIO_ADDR_clear(BIO_ADDR *ap);
 154 \& int BIO_ADDR_rawmake(BIO_ADDR *ap, int family,
 155 \&                      const void *where, size_t wherelen, unsigned short port);
 156 \& int BIO_ADDR_family(const BIO_ADDR *ap);
 157 \& int BIO_ADDR_rawaddress(const BIO_ADDR *ap, void *p, size_t *l);
 158 \& unsigned short BIO_ADDR_rawport(const BIO_ADDR *ap);
 159 \& char *BIO_ADDR_hostname_string(const BIO_ADDR *ap, int numeric);
 160 \& char *BIO_ADDR_service_string(const BIO_ADDR *ap, int numeric);
 161 \& char *BIO_ADDR_path_string(const BIO_ADDR *ap);
 162 .Ve
 163 .SH "DESCRIPTION"
 164 .IX Header "DESCRIPTION"
 165 The \fB\s-1BIO_ADDR\s0\fR type is a wrapper around all types of socket
 166 addresses that OpenSSL deals with, currently transparently
 167 supporting \s-1AF_INET, AF_INET6\s0 and \s-1AF_UNIX\s0 according to what's
 168 available on the platform at hand.
 169 .PP
 170 \&\fBBIO_ADDR_new()\fR creates a new unfilled \fB\s-1BIO_ADDR\s0\fR, to be used
 171 with routines that will fill it with information, such as
 172 \&\fBBIO_accept_ex()\fR.
 173 .PP
 174 \&\fBBIO_ADDR_free()\fR frees a \fB\s-1BIO_ADDR\s0\fR created with \fBBIO_ADDR_new()\fR.
 175 .PP
 176 \&\fBBIO_ADDR_clear()\fR clears any data held within the provided \fB\s-1BIO_ADDR\s0\fR and sets
 177 it back to an uninitialised state.
 178 .PP
 179 \&\fBBIO_ADDR_rawmake()\fR takes a protocol \fBfamily\fR, an byte array of
 180 size \fBwherelen\fR with an address in network byte order pointed at
 181 by \fBwhere\fR and a port number in network byte order in \fBport\fR (except
 182 for the \fB\s-1AF_UNIX\s0\fR protocol family, where \fBport\fR is meaningless and
 183 therefore ignored) and populates the given \fB\s-1BIO_ADDR\s0\fR with them.
 184 In case this creates a \fB\s-1AF_UNIX\s0\fR \fB\s-1BIO_ADDR\s0\fR, \fBwherelen\fR is expected
 185 to be the length of the path string (not including the terminating
 186 \&\s-1NUL,\s0 such as the result of a call to \fBstrlen()\fR).
 187 \&\fIRead on about the addresses in \*(L"\s-1RAW ADDRESSES\*(R"\s0 below\fR.
 188 .PP
 189 \&\fBBIO_ADDR_family()\fR returns the protocol family of the given
 190 \&\fB\s-1BIO_ADDR\s0\fR.  The possible non-error results are one of the
 191 constants \s-1AF_INET, AF_INET6\s0 and \s-1AF_UNIX.\s0 It will also return \s-1AF_UNSPEC\s0 if the
 192 \&\s-1BIO_ADDR\s0 has not been initialised.
 193 .PP
 194 \&\fBBIO_ADDR_rawaddress()\fR will write the raw address of the given
 195 \&\fB\s-1BIO_ADDR\s0\fR in the area pointed at by \fBp\fR if \fBp\fR is non-NULL,
 196 and will set \fB*l\fR to be the amount of bytes the raw address
 197 takes up if \fBl\fR is non-NULL.
 198 A technique to only find out the size of the address is a call
 199 with \fBp\fR set to \fB\s-1NULL\s0\fR.  The raw address will be in network byte
 200 order, most significant byte first.
 201 In case this is a \fB\s-1AF_UNIX\s0\fR \fB\s-1BIO_ADDR\s0\fR, \fBl\fR gets the length of the
 202 path string (not including the terminating \s-1NUL,\s0 such as the result of
 203 a call to \fBstrlen()\fR).
 204 \&\fIRead on about the addresses in \*(L"\s-1RAW ADDRESSES\*(R"\s0 below\fR.
 205 .PP
 206 \&\fBBIO_ADDR_rawport()\fR returns the raw port of the given \fB\s-1BIO_ADDR\s0\fR.
 207 The raw port will be in network byte order.
 208 .PP
 209 \&\fBBIO_ADDR_hostname_string()\fR returns a character string with the
 210 hostname of the given \fB\s-1BIO_ADDR\s0\fR.  If \fBnumeric\fR is 1, the string
 211 will contain the numerical form of the address.  This only works for
 212 \&\fB\s-1BIO_ADDR\s0\fR of the protocol families \s-1AF_INET\s0 and \s-1AF_INET6.\s0  The
 213 returned string has been allocated on the heap and must be freed
 214 with \fBOPENSSL_free()\fR.
 215 .PP
 216 \&\fBBIO_ADDR_service_string()\fR returns a character string with the
 217 service name of the port of the given \fB\s-1BIO_ADDR\s0\fR.  If \fBnumeric\fR
 218 is 1, the string will contain the port number.  This only works
 219 for \fB\s-1BIO_ADDR\s0\fR of the protocol families \s-1AF_INET\s0 and \s-1AF_INET6.\s0  The
 220 returned string has been allocated on the heap and must be freed
 221 with \fBOPENSSL_free()\fR.
 222 .PP
 223 \&\fBBIO_ADDR_path_string()\fR returns a character string with the path
 224 of the given \fB\s-1BIO_ADDR\s0\fR.  This only works for \fB\s-1BIO_ADDR\s0\fR of the
 225 protocol family \s-1AF_UNIX.\s0  The returned string has been allocated
 226 on the heap and must be freed with \fBOPENSSL_free()\fR.
 227 .SH "RAW ADDRESSES"
 228 .IX Header "RAW ADDRESSES"
 229 Both \fBBIO_ADDR_rawmake()\fR and \fBBIO_ADDR_rawaddress()\fR take a pointer to a
 230 network byte order address of a specific site.  Internally, those are
 231 treated as a pointer to \fBstruct in_addr\fR (for \fB\s-1AF_INET\s0\fR), \fBstruct
 232 in6_addr\fR (for \fB\s-1AF_INET6\s0\fR) or \fBchar *\fR (for \fB\s-1AF_UNIX\s0\fR), all
 233 depending on the protocol family the address is for.
 234 .SH "RETURN VALUES"
 235 .IX Header "RETURN VALUES"
 236 The string producing functions \fBBIO_ADDR_hostname_string()\fR,
 237 \&\fBBIO_ADDR_service_string()\fR and \fBBIO_ADDR_path_string()\fR will
 238 return \fB\s-1NULL\s0\fR on error and leave an error indication on the
 239 OpenSSL error stack.
 240 .PP
 241 All other functions described here return 0 or \fB\s-1NULL\s0\fR when the
 242 information they should return isn't available.
 243 .SH "SEE ALSO"
 244 .IX Header "SEE ALSO"
 245 \&\fBBIO_connect\fR\|(3), \fBBIO_s_connect\fR\|(3)
 246 .SH "COPYRIGHT"
 247 .IX Header "COPYRIGHT"
 248 Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
 249 .PP
 250 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 251 this file except in compliance with the License.  You can obtain a copy
 252 in the file \s-1LICENSE\s0 in the source distribution or at
 253 <https://www.openssl.org/source/license.html>.