doc/man3/BIO_ADDR.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 BIO_ADDR, BIO_ADDR_new, BIO_ADDR_copy, BIO_ADDR_dup, BIO_ADDR_clear,
   6 BIO_ADDR_free, BIO_ADDR_rawmake,
   7 BIO_ADDR_family, BIO_ADDR_rawaddress, BIO_ADDR_rawport,
   8 BIO_ADDR_hostname_string, BIO_ADDR_service_string,
   9 BIO_ADDR_path_string - BIO_ADDR routines
  10
  11 =head1 SYNOPSIS
  12
  13  #include <sys/types.h>
  14  #include <openssl/bio.h>
  15
  16  typedef union bio_addr_st BIO_ADDR;
  17
  18  BIO_ADDR *BIO_ADDR_new(void);
  19  int BIO_ADDR_copy(BIO_ADDR *dst, const BIO_ADDR *src);
  20  BIO_ADDR *BIO_ADDR_dup(const BIO_ADDR *ap);
  21  void BIO_ADDR_free(BIO_ADDR *);
  22  void BIO_ADDR_clear(BIO_ADDR *ap);
  23  int BIO_ADDR_rawmake(BIO_ADDR *ap, int family,
  24                       const void *where, size_t wherelen, unsigned short port);
  25  int BIO_ADDR_family(const BIO_ADDR *ap);
  26  int BIO_ADDR_rawaddress(const BIO_ADDR *ap, void *p, size_t *l);
  27  unsigned short BIO_ADDR_rawport(const BIO_ADDR *ap);
  28  char *BIO_ADDR_hostname_string(const BIO_ADDR *ap, int numeric);
  29  char *BIO_ADDR_service_string(const BIO_ADDR *ap, int numeric);
  30  char *BIO_ADDR_path_string(const BIO_ADDR *ap);
  31
  32 =head1 DESCRIPTION
  33
  34 The B<BIO_ADDR> type is a wrapper around all types of socket
  35 addresses that OpenSSL deals with, currently transparently
  36 supporting AF_INET, AF_INET6 and AF_UNIX according to what's
  37 available on the platform at hand.
  38
  39 BIO_ADDR_new() creates a new unfilled B<BIO_ADDR>, to be used
  40 with routines that will fill it with information, such as
  41 BIO_accept_ex().
  42
  43 BIO_ADDR_copy() copies the contents of B<src> into B<dst>. Neither B<src> or
  44 B<dst> can be NULL.
  45
  46 BIO_ADDR_dup() creates a new B<BIO_ADDR>, with a copy of the
  47 address data in B<ap>.
  48
  49 BIO_ADDR_free() frees a B<BIO_ADDR> created with BIO_ADDR_new()
  50 or BIO_ADDR_dup();
  51
  52 BIO_ADDR_clear() clears any data held within the provided B<BIO_ADDR> and sets
  53 it back to an uninitialised state.
  54
  55 BIO_ADDR_rawmake() takes a protocol B<family>, a byte array of
  56 size B<wherelen> with an address in network byte order pointed at
  57 by B<where> and a port number in network byte order in B<port> (except
  58 for the B<AF_UNIX> protocol family, where B<port> is meaningless and
  59 therefore ignored) and populates the given B<BIO_ADDR> with them.
  60 In case this creates a B<AF_UNIX> B<BIO_ADDR>, B<wherelen> is expected
  61 to be the length of the path string (not including the terminating
  62 NUL, such as the result of a call to strlen()).
  63 Read on about the addresses in L</RAW ADDRESSES> below.
  64
  65 BIO_ADDR_family() returns the protocol family of the given
  66 B<BIO_ADDR>.  The possible non-error results are one of the
  67 constants AF_INET, AF_INET6 and AF_UNIX. It will also return AF_UNSPEC if the
  68 BIO_ADDR has not been initialised.
  69
  70 BIO_ADDR_rawaddress() will write the raw address of the given
  71 B<BIO_ADDR> in the area pointed at by B<p> if B<p> is non-NULL,
  72 and will set B<*l> to be the amount of bytes the raw address
  73 takes up if B<l> is non-NULL.
  74 A technique to only find out the size of the address is a call
  75 with B<p> set to B<NULL>.  The raw address will be in network byte
  76 order, most significant byte first.
  77 In case this is a B<AF_UNIX> B<BIO_ADDR>, B<l> gets the length of the
  78 path string (not including the terminating NUL, such as the result of
  79 a call to strlen()).
  80 Read on about the addresses in L</RAW ADDRESSES> below.
  81
  82 BIO_ADDR_rawport() returns the raw port of the given B<BIO_ADDR>.
  83 The raw port will be in network byte order.
  84
  85 BIO_ADDR_hostname_string() returns a character string with the
  86 hostname of the given B<BIO_ADDR>.  If B<numeric> is 1, the string
  87 will contain the numerical form of the address.  This only works for
  88 B<BIO_ADDR> of the protocol families AF_INET and AF_INET6.  The
  89 returned string has been allocated on the heap and must be freed
  90 with OPENSSL_free().
  91
  92 BIO_ADDR_service_string() returns a character string with the
  93 service name of the port of the given B<BIO_ADDR>.  If B<numeric>
  94 is 1, the string will contain the port number.  This only works
  95 for B<BIO_ADDR> of the protocol families AF_INET and AF_INET6.  The
  96 returned string has been allocated on the heap and must be freed
  97 with OPENSSL_free().
  98
  99 BIO_ADDR_path_string() returns a character string with the path
 100 of the given B<BIO_ADDR>.  This only works for B<BIO_ADDR> of the
 101 protocol family AF_UNIX.  The returned string has been allocated
 102 on the heap and must be freed with OPENSSL_free().
 103
 104 =head1 RAW ADDRESSES
 105
 106 Both BIO_ADDR_rawmake() and BIO_ADDR_rawaddress() take a pointer to a
 107 network byte order address of a specific site.  Internally, those are
 108 treated as a pointer to B<struct in_addr> (for B<AF_INET>), B<struct
 109 in6_addr> (for B<AF_INET6>) or B<char *> (for B<AF_UNIX>), all
 110 depending on the protocol family the address is for.
 111
 112 =head1 RETURN VALUES
 113
 114 The string producing functions BIO_ADDR_hostname_string(),
 115 BIO_ADDR_service_string() and BIO_ADDR_path_string() will
 116 return B<NULL> on error and leave an error indication on the
 117 OpenSSL error stack.
 118
 119 BIO_ADDR_copy() returns 1 on success or 0 on error.
 120
 121 All other functions described here return 0 or B<NULL> when the
 122 information they should return isn't available.
 123
 124 =head1 SEE ALSO
 125
 126 L<BIO_connect(3)>, L<BIO_s_connect(3)>
 127
 128 =head1 HISTORY
 129
 130 BIO_ADDR_copy() and BIO_ADDR_dup() were added in OpenSSL 3.2.
 131
 132 =head1 COPYRIGHT
 133
 134 Copyright 2016-2023 The OpenSSL Project Authors. All Rights Reserved.
 135
 136 Licensed under the Apache License 2.0 (the "License").  You may not use
 137 this file except in compliance with the License.  You can obtain a copy
 138 in the file LICENSE in the source distribution or at
 139 L<https://www.openssl.org/source/license.html>.
 140
 141 =cut