lib/libc/net/getifmaddrs.3

   1 .\" Copyright (c) 2003 Bruce M. Simpson. All rights reserved.
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\"
   9 .\" THIS SOFTWARE IS PROVIDED BY Bruce M. Simpson ``AS IS'' AND
  10 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  11 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  12 .\" ARE DISCLAIMED.  IN NO EVENT SHALL Bruce M. Simpson BE LIABLE
  13 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  14 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  15 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  16 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  17 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  18 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  19 .\" SUCH DAMAGE.
  20 .\"
  21 .\" $FreeBSD$
  22 .\"
  23 .Dd November 14, 2003
  24 .Dt GETIFMADDRS 3
  25 .Os
  26 .Sh NAME
  27 .Nm getifmaddrs
  28 .Nd get multicast group memberships
  29 .Sh SYNOPSIS
  30 .In sys/types.h
  31 .In sys/socket.h
  32 .In ifaddrs.h
  33 .Ft int
  34 .Fn getifmaddrs "struct ifmaddrs **ifmap"
  35 .Ft void
  36 .Fn freeifmaddrs "struct ifmaddrs *ifmp"
  37 .Sh DESCRIPTION
  38 The
  39 .Fn getifmaddrs
  40 function stores a reference to a linked list of the multicast memberships
  41 on the local machine in the memory referenced by
  42 .Fa ifmap .
  43 The list consists of
  44 .Vt ifmaddrs
  45 structures, as defined in the include file
  46 .In ifaddrs.h .
  47 The
  48 .Vt ifmaddrs
  49 structure contains at least the following entries:
  50 .Bd -literal
  51     struct ifmaddrs   *ifma_next;     /* Pointer to next struct */
  52     struct sockaddr   *ifma_name;     /* Interface name (AF_LINK) */
  53     struct sockaddr   *ifma_addr;     /* Multicast address */
  54     struct sockaddr   *ifma_lladdr;   /* Link-layer translation, if any */
  55 .Ed
  56 .Pp
  57 The
  58 .Va ifma_next
  59 field contains a pointer to the next structure on the list.
  60 This field is
  61 .Dv NULL
  62 in last structure on the list.
  63 .Pp
  64 The
  65 .Va ifma_name
  66 field references an
  67 .Dv AF_LINK
  68 address structure, containing the name of the
  69 interface where the membership exists.
  70 .Pp
  71 The
  72 .Va ifma_addr
  73 references the address that this membership is for.
  74 .Pp
  75 The
  76 .Va ifma_lladdr
  77 field references a link-layer translation for the protocol-level address in
  78 .Va ifma_addr ,
  79 if one is set, otherwise it is
  80 .Dv NULL .
  81 .Pp
  82 The data returned by
  83 .Fn getifmaddrs
  84 is dynamically allocated and should be freed using
  85 .Fn freeifmaddrs
  86 when no longer needed.
  87 .Sh RETURN VALUES
  88 .Rv -std getifmaddrs
  89 .Sh ERRORS
  90 The
  91 .Fn getifmaddrs
  92 may fail and set
  93 .Va errno
  94 for any of the errors specified for the library routines
  95 .Xr malloc 3
  96 or
  97 .Xr sysctl 3 .
  98 .Sh SEE ALSO
  99 .Xr sysctl 3 ,
 100 .Xr networking 4 ,
 101 .Xr ifconfig 8
 102 .Sh HISTORY
 103 The
 104 .Fn getifmaddrs
 105 function first appeared in
 106 .Fx 5.2 .
 107 .Sh BUGS
 108 If both
 109 .In net/if.h
 110 and
 111 .In ifaddrs.h
 112 are being included,
 113 .In net/if.h
 114 .Em must
 115 be included before
 116 .In ifaddrs.h .