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