Debian Codegraph @

upstream/debian-unstable/man3/BIO_ADDR.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "BIO_ADDR 3SSL"
58 .TH BIO_ADDR 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 BIO_ADDR, BIO_ADDR_new, BIO_ADDR_copy, BIO_ADDR_dup, BIO_ADDR_clear,
65 BIO_ADDR_free, BIO_ADDR_rawmake,
66 BIO_ADDR_family, BIO_ADDR_rawaddress, BIO_ADDR_rawport,
67 BIO_ADDR_hostname_string, BIO_ADDR_service_string,
68 BIO_ADDR_path_string \- BIO_ADDR routines
69 .SH SYNOPSIS
70 .IX Header "SYNOPSIS"
71 .Vb 2
72 \& #include <sys/types.h>
73 \& #include <openssl/bio.h>
74 \&
75 \& typedef union bio_addr_st BIO_ADDR;
76 \&
77 \& BIO_ADDR *BIO_ADDR_new(void);
78 \& int BIO_ADDR_copy(BIO_ADDR *dst, const BIO_ADDR *src);
79 \& BIO_ADDR *BIO_ADDR_dup(const BIO_ADDR *ap);
80 \& void BIO_ADDR_free(BIO_ADDR *ap);
81 \& void BIO_ADDR_clear(BIO_ADDR *ap);
82 \& int BIO_ADDR_rawmake(BIO_ADDR *ap, int family,
83 \& const void *where, size_t wherelen, unsigned short port);
84 \& int BIO_ADDR_family(const BIO_ADDR *ap);
85 \& int BIO_ADDR_rawaddress(const BIO_ADDR *ap, void *p, size_t *l);
86 \& unsigned short BIO_ADDR_rawport(const BIO_ADDR *ap);
87 \& char *BIO_ADDR_hostname_string(const BIO_ADDR *ap, int numeric);
88 \& char *BIO_ADDR_service_string(const BIO_ADDR *ap, int numeric);
89 \& char *BIO_ADDR_path_string(const BIO_ADDR *ap);
90 .Ve
91 .SH DESCRIPTION
92 .IX Header "DESCRIPTION"
93 The \fBBIO_ADDR\fR type is a wrapper around all types of socket
94 addresses that OpenSSL deals with, currently transparently
95 supporting AF_INET, AF_INET6 and AF_UNIX according to what's
96 available on the platform at hand.
97 .PP
98 \&\fBBIO_ADDR_new()\fR creates a new unfilled \fBBIO_ADDR\fR, to be used
99 with routines that will fill it with information, such as
100 \&\fBBIO_accept_ex()\fR.
101 .PP
102 \&\fBBIO_ADDR_copy()\fR copies the contents of \fBsrc\fR into \fBdst\fR. Neither \fBsrc\fR or
103 \&\fBdst\fR can be NULL.
104 .PP
105 \&\fBBIO_ADDR_dup()\fR creates a new \fBBIO_ADDR\fR, with a copy of the
106 address data in \fBap\fR.
107 .PP
108 \&\fBBIO_ADDR_free()\fR frees a \fBBIO_ADDR\fR created with \fBBIO_ADDR_new()\fR
109 or \fBBIO_ADDR_dup()\fR. If the argument is NULL, nothing is done.
110 .PP
111 \&\fBBIO_ADDR_clear()\fR clears any data held within the provided \fBBIO_ADDR\fR and sets
112 it back to an uninitialised state.
113 .PP
114 \&\fBBIO_ADDR_rawmake()\fR takes a protocol \fBfamily\fR, a byte array of
115 size \fBwherelen\fR with an address in network byte order pointed at
116 by \fBwhere\fR and a port number in network byte order in \fBport\fR (except
117 for the \fBAF_UNIX\fR protocol family, where \fBport\fR is meaningless and
118 therefore ignored) and populates the given \fBBIO_ADDR\fR with them.
119 In case this creates a \fBAF_UNIX\fR \fBBIO_ADDR\fR, \fBwherelen\fR is expected
120 to be the length of the path string (not including the terminating
121 NUL, such as the result of a call to \fBstrlen()\fR).
122 Read on about the addresses in "RAW ADDRESSES" below.
123 .PP
124 \&\fBBIO_ADDR_family()\fR returns the protocol family of the given
125 \&\fBBIO_ADDR\fR. The possible non-error results are one of the
126 constants AF_INET, AF_INET6 and AF_UNIX. It will also return AF_UNSPEC if the
127 BIO_ADDR has not been initialised.
128 .PP
129 \&\fBBIO_ADDR_rawaddress()\fR will write the raw address of the given
130 \&\fBBIO_ADDR\fR in the area pointed at by \fBp\fR if \fBp\fR is non-NULL,
131 and will set \fB*l\fR to be the amount of bytes the raw address
132 takes up if \fBl\fR is non-NULL.
133 A technique to only find out the size of the address is a call
134 with \fBp\fR set to \fBNULL\fR. The raw address will be in network byte
135 order, most significant byte first.
136 In case this is a \fBAF_UNIX\fR \fBBIO_ADDR\fR, \fBl\fR gets the length of the
137 path string (not including the terminating NUL, such as the result of
138 a call to \fBstrlen()\fR).
139 Read on about the addresses in "RAW ADDRESSES" below.
140 .PP
141 \&\fBBIO_ADDR_rawport()\fR returns the raw port of the given \fBBIO_ADDR\fR.
142 The raw port will be in network byte order.
143 .PP
144 \&\fBBIO_ADDR_hostname_string()\fR returns a character string with the
145 hostname of the given \fBBIO_ADDR\fR. If \fBnumeric\fR is 1, the string
146 will contain the numerical form of the address. This only works for
147 \&\fBBIO_ADDR\fR of the protocol families AF_INET and AF_INET6. The
148 returned string has been allocated on the heap and must be freed
149 with \fBOPENSSL_free()\fR.
150 .PP
151 \&\fBBIO_ADDR_service_string()\fR returns a character string with the
152 service name of the port of the given \fBBIO_ADDR\fR. If \fBnumeric\fR
153 is 1, the string will contain the port number. This only works
154 for \fBBIO_ADDR\fR of the protocol families AF_INET and AF_INET6. The
155 returned string has been allocated on the heap and must be freed
156 with \fBOPENSSL_free()\fR.
157 .PP
158 \&\fBBIO_ADDR_path_string()\fR returns a character string with the path
159 of the given \fBBIO_ADDR\fR. This only works for \fBBIO_ADDR\fR of the
160 protocol family AF_UNIX. The returned string has been allocated
161 on the heap and must be freed with \fBOPENSSL_free()\fR.
162 .SH "RAW ADDRESSES"
163 .IX Header "RAW ADDRESSES"
164 Both \fBBIO_ADDR_rawmake()\fR and \fBBIO_ADDR_rawaddress()\fR take a pointer to a
165 network byte order address of a specific site. Internally, those are
166 treated as a pointer to \fBstruct in_addr\fR (for \fBAF_INET\fR), \fBstruct
167 in6_addr\fR (for \fBAF_INET6\fR) or \fBchar *\fR (for \fBAF_UNIX\fR), all
168 depending on the protocol family the address is for.
169 .SH "RETURN VALUES"
170 .IX Header "RETURN VALUES"
171 The string producing functions \fBBIO_ADDR_hostname_string()\fR,
172 \&\fBBIO_ADDR_service_string()\fR and \fBBIO_ADDR_path_string()\fR will
173 return \fBNULL\fR on error and leave an error indication on the
174 OpenSSL error stack.
175 .PP
176 \&\fBBIO_ADDR_copy()\fR returns 1 on success or 0 on error.
177 .PP
178 All other functions described here return 0 or \fBNULL\fR when the
179 information they should return isn't available.
180 .SH "SEE ALSO"
181 .IX Header "SEE ALSO"
182 \&\fBBIO_connect\fR\|(3), \fBBIO_s_connect\fR\|(3)
183 .SH HISTORY
184 .IX Header "HISTORY"
185 \&\fBBIO_ADDR_copy()\fR and \fBBIO_ADDR_dup()\fR were added in OpenSSL 3.2.
186 .SH COPYRIGHT
187 .IX Header "COPYRIGHT"
188 Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved.
189 .PP
190 Licensed under the Apache License 2.0 (the "License"). You may not use
191 this file except in compliance with the License. You can obtain a copy
192 in the file LICENSE in the source distribution or at
193 <https://www.openssl.org/source/license.html>.