6/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 July 15, 2002
  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 net/if.h
  38 .Ft "unsigned int"
  39 .Fn if_nametoindex "const char *ifname"
  40 .Ft "char *"
  41 .Fn if_indextoname "unsigned int ifindex" "char *ifname"
  42 .Ft "struct if_nameindex *"
  43 .Fn if_nameindex "void"
  44 .Ft void
  45 .Fn if_freenameindex "struct if_nameindex *ptr"
  46 .Sh DESCRIPTION
  47 The
  48 .Fn if_nametoindex
  49 function maps the interface name specified in
  50 .Fa ifname
  51 to its corresponding index.
  52 If the specified interface does not exist, it returns 0.
  53 .Pp
  54 The
  55 .Fn if_indextoname
  56 function maps the interface index specified in
  57 .Fa ifindex
  58 to it corresponding name, which is copied into the
  59 buffer pointed to by
  60 .Fa ifname ,
  61 which must be of at least
  62 .Dv IFNAMSIZ
  63 bytes.
  64 This pointer is also the return value of the function.
  65 If there is no interface corresponding to the specified
  66 index,
  67 .Dv NULL
  68 is returned.
  69 .Pp
  70 The
  71 .Fn if_nameindex
  72 function returns an array of
  73 .Vt if_nameindex
  74 structures, one structure per interface, as
  75 defined in the include file
  76 .In net/if.h .
  77 The
  78 .Vt if_nameindex
  79 structure contains at least the following entries:
  80 .Bd -literal
  81     unsigned int   if_index;  /* 1, 2, ... */
  82     char          *if_name;   /* null terminated name: "le0", ... */
  83 .Ed
  84 .Pp
  85 The end of the array of structures is indicated by a structure with an
  86 .Va if_index
  87 of 0 and an
  88 .Va if_name
  89 of
  90 .Dv NULL .
  91 A
  92 .Dv NULL
  93 pointer is returned upon an error.
  94 .Pp
  95 The
  96 .Fn if_freenameindex
  97 function frees the dynamic memory that was
  98 allocated by
  99 .Fn if_nameindex .
 100 .Sh RETURN VALUES
 101 Upon successful completion,
 102 .Fn if_nametoindex
 103 returns the index number of the interface.
 104 If the interface is not found, a value of 0 is returned and
 105 .Va errno
 106 is set to
 107 .Er ENXIO .
 108 A value of 0 is also returned if an error
 109 occurs while retrieving the list of interfaces via
 110 .Xr getifaddrs 3 .
 111 .Pp
 112 Upon successful completion,
 113 .Fn if_indextoname
 114 returns
 115 .Fa ifname .
 116 If the interface is not found, a
 117 .Dv NULL
 118 pointer is returned and
 119 .Va errno
 120 is set to
 121 .Er ENXIO .
 122 A
 123 .Dv NULL
 124 pointer is also returned if an error
 125 occurs while retrieving the list of interfaces via
 126 .Xr getifaddrs 3 .
 127 .Pp
 128 The
 129 .Fn if_nameindex
 130 returns a
 131 .Dv NULL
 132 pointer if an error
 133 occurs while retrieving the list of interfaces via
 134 .Xr getifaddrs 3 ,
 135 or if sufficient memory cannot be allocated.
 136 .Sh SEE ALSO
 137 .Xr getifaddrs 3 ,
 138 .Xr networking 4
 139 .Sh STANDARDS
 140 The
 141 .Fn if_nametoindex ,
 142 .Fn if_indextoname ,
 143 .Fn if_nameindex ,
 144 and
 145 .Fn if_freenameindex
 146 functions conform to
 147 .%T "RFC 2553" .
 148 .Sh HISTORY
 149 The implementation first appeared in BSDi
 150 .Bsx .