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