lib/libc/net/if_indextoname.3

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