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 May 21, 2013
  24 .Dt GETIFMADDRS 3
  25 .Os
  26 .Sh NAME
  27 .Nm getifmaddrs
  28 .Nd get multicast group memberships
  29 .Sh SYNOPSIS
  30 .In ifaddrs.h
  31 .Ft int
  32 .Fn getifmaddrs "struct ifmaddrs **ifmap"
  33 .Ft void
  34 .Fn freeifmaddrs "struct ifmaddrs *ifmp"
  35 .Sh DESCRIPTION
  36 The
  37 .Fn getifmaddrs
  38 function stores a reference to a linked list of the multicast memberships
  39 on the local machine in the memory referenced by
  40 .Fa ifmap .
  41 The list consists of
  42 .Vt ifmaddrs
  43 structures, as defined in the include file
  44 .In ifaddrs.h .
  45 The
  46 .Vt ifmaddrs
  47 structure contains at least the following entries:
  48 .Bd -literal
  49     struct ifmaddrs   *ifma_next;     /* Pointer to next struct */
  50     struct sockaddr   *ifma_name;     /* Interface name (AF_LINK) */
  51     struct sockaddr   *ifma_addr;     /* Multicast address */
  52     struct sockaddr   *ifma_lladdr;   /* Link-layer translation, if any */
  53 .Ed
  54 .Pp
  55 The
  56 .Va ifma_next
  57 field contains a pointer to the next structure on the list.
  58 This field is
  59 .Dv NULL
  60 in last structure on the list.
  61 .Pp
  62 The
  63 .Va ifma_name
  64 field references an
  65 .Dv AF_LINK
  66 address structure, containing the name of the
  67 interface where the membership exists.
  68 .Pp
  69 The
  70 .Va ifma_addr
  71 references the address that this membership is for.
  72 .Pp
  73 The
  74 .Va ifma_lladdr
  75 field references a link-layer translation for the protocol-level address in
  76 .Va ifma_addr ,
  77 if one is set, otherwise it is
  78 .Dv NULL .
  79 .Pp
  80 The data returned by
  81 .Fn getifmaddrs
  82 is dynamically allocated and should be freed using
  83 .Fn freeifmaddrs
  84 when no longer needed.
  85 .Sh RETURN VALUES
  86 .Rv -std getifmaddrs
  87 .Sh ERRORS
  88 The
  89 .Fn getifmaddrs
  90 may fail and set
  91 .Va errno
  92 for any of the errors specified for the library routines
  93 .Xr malloc 3
  94 or
  95 .Xr sysctl 3 .
  96 .Sh SEE ALSO
  97 .Xr sysctl 3 ,
  98 .Xr networking 4 ,
  99 .Xr ifconfig 8
 100 .Sh HISTORY
 101 The
 102 .Fn getifmaddrs
 103 function first appeared in
 104 .Fx 5.2 .
 105 .Sh BUGS
 106 If both
 107 .In net/if.h
 108 and
 109 .In ifaddrs.h
 110 are being included,
 111 .In net/if.h
 112 .Em must
 113 be included before
 114 .In ifaddrs.h .