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