On Fri, Nov 16, 2012 at 6:28 PM, YOSHIFUJI Hideaki
<yoshfuji@xxxxxxxxxxxxxx> wrote:
> Please review.
Thanks Hideaki.
I've merged this into a branch, made a number of fixes, and added an
example program. Could you check my changes in the diff below. (The
complete page is attached.)
Cheers,
Michael
diff --git a/man3/if_nameindex.3 b/man3/if_nameindex.3
index 60bfd39..23eaa5a 100644
--- a/man3/if_nameindex.3
+++ b/man3/if_nameindex.3
@@ -1,4 +1,5 @@
.\" Copyright (c) 2012 YOSHIFUJI Hideaki <yoshfuji@xxxxxxxxxxxxxx>
+.\" and Copyright (c) 2012 Michael Kerrisk <mtk.manpages@xxxxxxxxx>
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
@@ -20,7 +21,7 @@
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
-.TH IF_NAMEINDEX 3 2012-11-16 "GNU" "Linux Programmer's Manual"
+.TH IF_NAMEINDEX 3 2012-11-21 "GNU" "Linux Programmer's Manual"
.SH NAME
if_nameindex, if_freenameindex \- get network interface names and indexes
.SH SYNOPSIS
@@ -33,32 +34,34 @@ if_nameindex, if_freenameindex \- get network
interface names and indexes
.SH DESCRIPTION
The
.BR if_nameindex ()
-function creates an array of structures, one structure per
-interface, each describing network interface name and
-corresponding network index of the local system.
-
+function returns an array of
+.I if_nameindex
+structures, each containing information
+about one of the network interfaces on the local system.
The
.I if_nameindex
structure contains at least the following entries:
.sp
.in +4n
.nf
- unsigned int if_index; /* 1, 2, ... */
- char *if_name; /* null terminated name: "eth0", ... */
+ unsigned int if_index; /* Index of interface (1, 2, ...) */
+ char *if_name; /* Null-terminated name ("eth0", etc.) */
.fi
.in
.PP
The
.I if_index
-field contains the interface index,
-or zero if this is the last item of the array.
-.PP
+field contains the interface index.
The
.I ifa_name
-field points to the null-terminated interface name,
-or NULL pointer if this is the last item of the array.
+field points to the null-terminated interface name.
+The end of the array is indicated by entry with
+.I if_index
+set to zero and
+.I ifa_name
+set to NULL.
.PP
-The data returned by
+The data structure returned by
.BR if_nameindex ()
is dynamically allocated and should be freed using
.BR if_freenameindex ()
@@ -67,7 +70,7 @@ when no longer needed.
On success,
.BR if_nameindex ()
returns pointer to the array;
-on error, A NULL pointer is returned, and
+on error, a NULL pointer is returned, and
.I errno
is set appropriately.
.SH ERRORS
@@ -77,7 +80,7 @@ may fail and set
if:
.TP
.B ENOBUFS
-Sufficient resources unavailable.
+Insufficient resources unavailable.
.PP
.BR if_nameindex ()
may also fail for any of the errors specified for
@@ -92,13 +95,51 @@ or
.SH VERSIONS
The
.BR if_nameindex ()
-function first appeared in glibc 2.3, but before glibc 2.3.3,
+function first appeared in glibc 2.1, but before glibc 2.3.4,
the implementation only supported interfaces with IPv4 addresses.
-Support of interfaces without IPv4 addresses is only available
+Support of interfaces that don't have IPv4 addresses is only available
on kernels that support netlink.
+.SH EXAMPLE
+The program below demonstrates the use of the functions described
+on this page.
+An example of the output this program might produce is the following:
+.in +4n
+.nf
+$ \fB./a.out\fI
+1: lo
+2: wlan0
+3: em1
+.fi
+.in
+.SS Program source
+.nf
+#include <net/if.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+
+int
+main(int argc, char *argv[])
+{
+ struct if_nameindex *if_ni, *i;
+
+ if_ni = if_nameindex();
+ if (if_ni == NULL) {
+ perror("if_nameindex");
+ exit(EXIT_FAILURE);
+ }
+
+ for (i = if_ni; ! (i\->if_index == 0 && i\->if_name == NULL); i++)
+ printf("%d: %s\\n", i\->if_index, i\->if_name);
+
+ if_freenameindex(if_ni);
+
+ exit(EXIT_SUCCESS);
+}
+.fi
.SH CONFORMING TO
RFC\ 3493, POSIX.1-2001.
-.SH HISTORY
+
This function first appeared in BSDi.
.SH SEE ALSO
.BR getsockopt (2),
Attachment:
if_nameindex.3
Description: Binary data
