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