lib/libc/net/if_indextoname.3

   1 .\"     $KAME: if_indextoname.3,v 1.10 2000/11/24 08:13:51 itojun Exp $
   2 .\"     BSDI    Id: if_indextoname.3,v 2.2 2000/04/17 22:38:05 dab Exp
   3 .\"
   4 .\" Copyright (c) 1997, 2000
   5 .\"     Berkeley Software Design, Inc.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY Berkeley Software Design, Inc. ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL Berkeley Software Design, Inc. BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd November 23, 2005
  28 .Dt IF_NAMETOINDEX 3
  29 .Os
  30 .Sh NAME
  31 .Nm if_nametoindex ,
  32 .Nm if_indextoname ,
  33 .Nm if_nameindex ,
  34 .Nm if_freenameindex
  35 .Nd provide mappings between interface names and indexes
  36 .Sh SYNOPSIS
  37 .In sys/types.h
  38 .In sys/socket.h
  39 .In net/if.h
  40 .Ft "unsigned int"
  41 .Fn if_nametoindex "const char *ifname"
  42 .Ft "char *"
  43 .Fn if_indextoname "unsigned int ifindex" "char *ifname"
  44 .Ft "struct if_nameindex *"
  45 .Fn if_nameindex "void"
  46 .Ft void
  47 .Fn if_freenameindex "struct if_nameindex *ptr"
  48 .Sh DESCRIPTION
  49 The
  50 .Fn if_nametoindex
  51 function maps the interface name specified in
  52 .Fa ifname
  53 to its corresponding index.
  54 If the specified interface does not exist, it returns 0.
  55 .Pp
  56 The
  57 .Fn if_indextoname
  58 function maps the interface index specified in
  59 .Fa ifindex
  60 to it corresponding name, which is copied into the
  61 buffer pointed to by
  62 .Fa ifname ,
  63 which must be of at least
  64 .Dv IFNAMSIZ
  65 bytes.
  66 This pointer is also the return value of the function.
  67 If there is no interface corresponding to the specified
  68 index,
  69 .Dv NULL
  70 is returned.
  71 .Pp
  72 The
  73 .Fn if_nameindex
  74 function returns an array of
  75 .Vt if_nameindex
  76 structures, one structure per interface, as
  77 defined in the include file
  78 .In net/if.h .
  79 The
  80 .Vt if_nameindex
  81 structure contains at least the following entries:
  82 .Bd -literal
  83     unsigned int   if_index;  /* 1, 2, ... */
  84     char          *if_name;   /* null terminated name: "le0", ... */
  85 .Ed
  86 .Pp
  87 The end of the array of structures is indicated by a structure with an
  88 .Va if_index
  89 of 0 and an
  90 .Va if_name
  91 of
  92 .Dv NULL .
  93 A
  94 .Dv NULL
  95 pointer is returned upon an error.
  96 .Pp
  97 The
  98 .Fn if_freenameindex
  99 function frees the dynamic memory that was
 100 allocated by
 101 .Fn if_nameindex .
 102 .Sh RETURN VALUES
 103 Upon successful completion,
 104 .Fn if_nametoindex
 105 returns the index number of the interface.
 106 If the interface is not found, a value of 0 is returned and
 107 .Va errno
 108 is set to
 109 .Er ENXIO .
 110 A value of 0 is also returned if an error
 111 occurs while retrieving the list of interfaces via
 112 .Xr getifaddrs 3 .
 113 .Pp
 114 Upon successful completion,
 115 .Fn if_indextoname
 116 returns
 117 .Fa ifname .
 118 If the interface is not found, a
 119 .Dv NULL
 120 pointer is returned and
 121 .Va errno
 122 is set to
 123 .Er ENXIO .
 124 A
 125 .Dv NULL
 126 pointer is also returned if an error
 127 occurs while retrieving the list of interfaces via
 128 .Xr getifaddrs 3 .
 129 .Pp
 130 The
 131 .Fn if_nameindex
 132 returns a
 133 .Dv NULL
 134 pointer if an error
 135 occurs while retrieving the list of interfaces via
 136 .Xr getifaddrs 3 ,
 137 or if sufficient memory cannot be allocated.
 138 .Sh SEE ALSO
 139 .Xr getifaddrs 3 ,
 140 .Xr networking 4
 141 .Sh STANDARDS
 142 The
 143 .Fn if_nametoindex ,
 144 .Fn if_indextoname ,
 145 .Fn if_nameindex ,
 146 and
 147 .Fn if_freenameindex
 148 functions conform to
 149 .%T "RFC 2553" .
 150 .Sh HISTORY
 151 The implementation first appeared in BSDi
 152 .Bsx .