doc/crypto/BIO_ADDR.pod

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