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

   1 .\" Automatically generated by Pod::Man 4.14 (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_ADDRINFO 3"
 136 .TH BIO_ADDRINFO 3 "2020-09-22" "1.1.1h" "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_lookup_type, BIO_ADDRINFO, BIO_ADDRINFO_next, BIO_ADDRINFO_free, BIO_ADDRINFO_family, BIO_ADDRINFO_socktype, BIO_ADDRINFO_protocol, BIO_ADDRINFO_address, BIO_lookup_ex, BIO_lookup \&\- BIO_ADDRINFO type and 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_addrinfo_st BIO_ADDRINFO;
 150 \&
 151 \& enum BIO_lookup_type {
 152 \&     BIO_LOOKUP_CLIENT, BIO_LOOKUP_SERVER
 153 \& };
 154 \&
 155 \& int BIO_lookup_ex(const char *host, const char *service, int lookup_type,
 156 \&                   int family, int socktype, int protocol, BIO_ADDRINFO **res);
 157 \& int BIO_lookup(const char *node, const char *service,
 158 \&                enum BIO_lookup_type lookup_type,
 159 \&                int family, int socktype, BIO_ADDRINFO **res);
 160 \&
 161 \& const BIO_ADDRINFO *BIO_ADDRINFO_next(const BIO_ADDRINFO *bai);
 162 \& int BIO_ADDRINFO_family(const BIO_ADDRINFO *bai);
 163 \& int BIO_ADDRINFO_socktype(const BIO_ADDRINFO *bai);
 164 \& int BIO_ADDRINFO_protocol(const BIO_ADDRINFO *bai);
 165 \& const BIO_ADDR *BIO_ADDRINFO_address(const BIO_ADDRINFO *bai);
 166 \& void BIO_ADDRINFO_free(BIO_ADDRINFO *bai);
 167 .Ve
 168 .SH "DESCRIPTION"
 169 .IX Header "DESCRIPTION"
 170 The \fB\s-1BIO_ADDRINFO\s0\fR type is a wrapper for address information
 171 types provided on your platform.
 172 .PP
 173 \&\fB\s-1BIO_ADDRINFO\s0\fR normally forms a chain of several that can be
 174 picked at one by one.
 175 .PP
 176 \&\fBBIO_lookup_ex()\fR looks up a specified \fBhost\fR and \fBservice\fR, and
 177 uses \fBlookup_type\fR to determine what the default address should
 178 be if \fBhost\fR is \fB\s-1NULL\s0\fR. \fBfamily\fR, \fBsocktype\fR and \fBprotocol\fR are used to
 179 determine what protocol family, socket type and protocol should be used for
 180 the lookup.  \fBfamily\fR can be any of \s-1AF_INET, AF_INET6, AF_UNIX\s0 and
 181 \&\s-1AF_UNSPEC.\s0 \fBsocktype\fR can be \s-1SOCK_STREAM, SOCK_DGRAM\s0 or 0. Specifying 0
 182 indicates that any type can be used. \fBprotocol\fR specifies a protocol such as
 183 \&\s-1IPPROTO_TCP, IPPROTO_UDP\s0 or \s-1IPPORTO_SCTP.\s0 If set to 0 than any protocol can be
 184 used. \fBres\fR points at a pointer to hold the start of a \fB\s-1BIO_ADDRINFO\s0\fR
 185 chain.
 186 .PP
 187 For the family \fB\s-1AF_UNIX\s0\fR, \fBBIO_lookup_ex()\fR will ignore the \fBservice\fR
 188 parameter and expects the \fBnode\fR parameter to hold the path to the
 189 socket file.
 190 .PP
 191 \&\fBBIO_lookup()\fR does the same as \fBBIO_lookup_ex()\fR but does not provide the ability
 192 to select based on the protocol (any protocol may be returned).
 193 .PP
 194 \&\fBBIO_ADDRINFO_family()\fR returns the family of the given
 195 \&\fB\s-1BIO_ADDRINFO\s0\fR.  The result will be one of the constants
 196 \&\s-1AF_INET, AF_INET6\s0 and \s-1AF_UNIX.\s0
 197 .PP
 198 \&\fBBIO_ADDRINFO_socktype()\fR returns the socket type of the given
 199 \&\fB\s-1BIO_ADDRINFO\s0\fR.  The result will be one of the constants
 200 \&\s-1SOCK_STREAM\s0 and \s-1SOCK_DGRAM.\s0
 201 .PP
 202 \&\fBBIO_ADDRINFO_protocol()\fR returns the protocol id of the given
 203 \&\fB\s-1BIO_ADDRINFO\s0\fR.  The result will be one of the constants
 204 \&\s-1IPPROTO_TCP\s0 and \s-1IPPROTO_UDP.\s0
 205 .PP
 206 \&\fBBIO_ADDRINFO_address()\fR returns the underlying \fB\s-1BIO_ADDR\s0\fR
 207 of the given \fB\s-1BIO_ADDRINFO\s0\fR.
 208 .PP
 209 \&\fBBIO_ADDRINFO_next()\fR returns the next \fB\s-1BIO_ADDRINFO\s0\fR in the chain
 210 from the given one.
 211 .PP
 212 \&\fBBIO_ADDRINFO_free()\fR frees the chain of \fB\s-1BIO_ADDRINFO\s0\fR starting
 213 with the given one.
 214 .SH "RETURN VALUES"
 215 .IX Header "RETURN VALUES"
 216 \&\fBBIO_lookup_ex()\fR and \fBBIO_lookup()\fR return 1 on success and 0 when an error
 217 occurred, and will leave an error indication on the OpenSSL error stack in that
 218 case.
 219 .PP
 220 All other functions described here return 0 or \fB\s-1NULL\s0\fR when the
 221 information they should return isn't available.
 222 .SH "NOTES"
 223 .IX Header "NOTES"
 224 The \fBBIO_lookup_ex()\fR implementation uses the platform provided \fBgetaddrinfo()\fR
 225 function. On Linux it is known that specifying 0 for the protocol will not
 226 return any \s-1SCTP\s0 based addresses when calling \fBgetaddrinfo()\fR. Therefore, if an \s-1SCTP\s0
 227 address is required then the \fBprotocol\fR parameter to \fBBIO_lookup_ex()\fR should be
 228 explicitly set to \s-1IPPROTO_SCTP.\s0 The same may be true on other platforms.
 229 .SH "HISTORY"
 230 .IX Header "HISTORY"
 231 The \fBBIO_lookup_ex()\fR function was added in OpenSSL 1.1.1.
 232 .SH "COPYRIGHT"
 233 .IX Header "COPYRIGHT"
 234 Copyright 2016\-2020 The OpenSSL Project Authors. All Rights Reserved.
 235 .PP
 236 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 237 this file except in compliance with the License.  You can obtain a copy
 238 in the file \s-1LICENSE\s0 in the source distribution or at
 239 <https://www.openssl.org/source/license.html>.