Debian Codegraph @

upstream/debian-unstable/man3/if_nameindex.3

raw
1 '\" t
2 .\" Copyright 2012, YOSHIFUJI Hideaki/吉藤英明 <[email protected]>
3 .\" Copyright 2012, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .TH if_nameindex 3 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 if_nameindex, if_freenameindex \- get network interface names and indexes
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <net/if.h>
17 .P
18 .BI "struct if_nameindex *if_nameindex(" void );
19 .BI "void if_freenameindex(struct if_nameindex *" "ptr" );
20 .fi
21 .SH DESCRIPTION
22 The
23 .BR if_nameindex ()
24 function returns an array of
25 .I if_nameindex
26 structures, each containing information
27 about one of the network interfaces on the local system.
28 The
29 .I if_nameindex
30 structure contains at least the following entries:
31 .P
32 .in +4n
33 .EX
34 unsigned int if_index; /* Index of interface (1, 2, ...) */
35 char *if_name; /* Null\-terminated name ("eth0", etc.) */
36 .EE
37 .in
38 .P
39 The
40 .I if_index
41 field contains the interface index.
42 The
43 .I if_name
44 field points to the null-terminated interface name.
45 The end of the array is indicated by entry with
46 .I if_index
47 set to zero and
48 .I if_name
49 set to NULL.
50 .P
51 The data structure returned by
52 .BR if_nameindex ()
53 is dynamically allocated and should be freed using
54 .BR if_freenameindex ()
55 when no longer needed.
56 .SH RETURN VALUE
57 On success,
58 .BR if_nameindex ()
59 returns pointer to the array;
60 on error, NULL is returned, and
61 .I errno
62 is set to indicate the error.
63 .SH ERRORS
64 .BR if_nameindex ()
65 may fail and set
66 .I errno
67 if:
68 .TP
69 .B ENOBUFS
70 Insufficient resources available.
71 .P
72 .BR if_nameindex ()
73 may also fail for any of the errors specified for
74 .BR socket (2),
75 .BR bind (2),
76 .BR ioctl (2),
77 .BR getsockname (2),
78 .BR recvmsg (2),
79 .BR sendto (2),
80 or
81 .BR malloc (3).
82 .SH ATTRIBUTES
83 For an explanation of the terms used in this section, see
84 .BR attributes (7).
85 .TS
86 allbox;
87 lbx lb lb
88 l l l.
89 Interface Attribute Value
90 T{
91 .na
92 .nh
93 .BR if_nameindex (),
94 .BR if_freenameindex ()
95 T} Thread safety MT-Safe
96 .TE
97 .SH STANDARDS
98 POSIX.1-2008, RFC\ 3493.
99 .SH HISTORY
100 glibc 2.1.
101 POSIX.1-2001.
102 BSDi.
103 .P
104 Before glibc 2.3.4,
105 the implementation supported only interfaces with IPv4 addresses.
106 Support of interfaces that don't have IPv4 addresses is available only
107 on kernels that support netlink.
108 .SH EXAMPLES
109 The program below demonstrates the use of the functions described
110 on this page.
111 An example of the output this program might produce is the following:
112 .P
113 .in +4n
114 .EX
115 .RB $ " ./a.out" ;
116 1: lo
117 2: wlan0
118 3: em1
119 .EE
120 .in
121 .SS Program source
122 .\" SRC BEGIN (if_nameindex.c)
123 .EX
124 #include <net/if.h>
125 #include <stdio.h>
126 #include <stdlib.h>
127 #include <unistd.h>
128 \&
129 int
130 main(void)
131 {
132 struct if_nameindex *if_ni, *i;
133 \&
134 if_ni = if_nameindex();
135 if (if_ni == NULL) {
136 perror("if_nameindex");
137 exit(EXIT_FAILURE);
138 }
139 \&
140 for (i = if_ni; !(i\->if_index == 0 && i\->if_name == NULL); i++)
141 printf("%u: %s\[rs]n", i\->if_index, i\->if_name);
142 \&
143 if_freenameindex(if_ni);
144 \&
145 exit(EXIT_SUCCESS);
146 }
147 .EE
148 .\" SRC END
149 .SH SEE ALSO
150 .BR getsockopt (2),
151 .BR setsockopt (2),
152 .BR getifaddrs (3),
153 .BR if_indextoname (3),
154 .BR if_nametoindex (3),
155 .BR ifconfig (8)