1.. _promiscuous_interface:
2
3Promiscuous Mode
4################
5
6.. contents::
7    :local:
8    :depth: 2
9
10Overview
11********
12
13Promiscuous mode is a mode for a network interface controller that
14causes it to pass all traffic it receives to the application rather than
15passing only the frames that the controller is specifically programmed
16to receive. This mode is normally used for packet sniffing as used
17to diagnose network connectivity issues by showing an application
18all the data being transferred over the network.  (See the
19`Wikipedia article on promiscuous mode
20<https://en.wikipedia.org/wiki/Promiscuous_mode>`_ for more information.)
21
22The network promiscuous APIs are used to enable and disable this mode,
23and to wait for and receive a network data to arrive. Not all network
24technologies or network device drivers support promiscuous mode.
25
26Sample usage
27************
28
29First the promiscuous mode needs to be turned ON by the application like this:
30
31.. code-block:: c
32
33	ret = net_promisc_mode_on(iface);
34	if (ret < 0) {
35		if (ret == -EALREADY) {
36			printf("Promiscuous mode already enabled\n");
37		} else {
38			printf("Cannot enable promiscuous mode for "
39			       "interface %p (%d)\n", iface, ret);
40		}
41	}
42
43
44If there is no error, then the application can start to wait for network data:
45
46.. code-block:: c
47
48	while (true) {
49		pkt = net_promisc_mode_wait_data(K_FOREVER);
50		if (pkt) {
51			print_info(pkt);
52		}
53
54		net_pkt_unref(pkt);
55	}
56
57
58Finally the promiscuous mode can be turned OFF by the application like this:
59
60.. code-block:: c
61
62	ret = net_promisc_mode_off(iface);
63	if (ret < 0) {
64		if (ret == -EALREADY) {
65			printf("Promiscuous mode already disabled\n");
66		} else {
67			printf("Cannot disable promiscuous mode for "
68			       "interface %p (%d)\n", iface, ret);
69		}
70	}
71
72
73See :zephyr:code-sample:`net-promiscuous-mode` for a more comprehensive example.
74
75
76API Reference
77*************
78
79.. doxygengroup:: promiscuous
80