[3.7] closes bpo-25041: Document AF_PACKET socket address format. (GH-9207)
(cherry picked from commit 731ff68eeef58babdf2b32dc9a73b141760c2be9)
Co-authored-by: Cheryl Sabella <cheryl.sabella@gmail.com>
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index cea0175..32e7c5e 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -173,10 +173,25 @@
.. versionadded:: 3.7
-- Certain other address families (:const:`AF_PACKET`, :const:`AF_CAN`)
- support specific representations.
+- :const:`AF_PACKET` is a low-level interface directly to network devices.
+ The packets are represented by the tuple
+ ``(ifname, proto[, pkttype[, hatype[, addr]]])`` where:
- .. XXX document them!
+ - *ifname* - String specifying the device name.
+ - *proto* - An in network-byte-order integer specifying the Ethernet
+ protocol number.
+ - *pkttype* - Optional integer specifying the packet type:
+
+ - ``PACKET_HOST`` (the default) - Packet addressed to the local host.
+ - ``PACKET_BROADCAST`` - Physical-layer broadcast packet.
+ - ``PACKET_MULTIHOST`` - Packet sent to a physical-layer multicast address.
+ - ``PACKET_OTHERHOST`` - Packet to some other host that has been caught by
+ a device driver in promiscuous mode.
+ - ``PACKET_OUTGOING`` - Packet originating from the local host that is
+ looped back to a packet socket.
+ - *hatype* - Optional integer specifying the ARP hardware address type.
+ - *addr* - Optional bytes-like object specifying the hardware physical
+ address, whose interpretation depends on the device.
If you use a hostname in the *host* portion of IPv4/v6 socket address, the
program may show a nondeterministic behavior, as Python uses the first address
@@ -376,6 +391,16 @@
.. versionadded:: 3.7
+.. data:: AF_PACKET
+ PF_PACKET
+ PACKET_*
+
+ Many constants of these forms, documented in the Linux documentation, are
+ also defined in the socket module.
+
+ Availability: Linux >= 2.2.
+
+
.. data:: AF_RDS
PF_RDS
SOL_RDS
@@ -469,12 +494,12 @@
Create a new socket using the given address family, socket type and protocol
number. The address family should be :const:`AF_INET` (the default),
- :const:`AF_INET6`, :const:`AF_UNIX`, :const:`AF_CAN` or :const:`AF_RDS`. The
- socket type should be :const:`SOCK_STREAM` (the default),
- :const:`SOCK_DGRAM`, :const:`SOCK_RAW` or perhaps one of the other ``SOCK_``
- constants. The protocol number is usually zero and may be omitted or in the
- case where the address family is :const:`AF_CAN` the protocol should be one
- of :const:`CAN_RAW`, :const:`CAN_BCM` or :const:`CAN_ISOTP`
+ :const:`AF_INET6`, :const:`AF_UNIX`, :const:`AF_CAN`, :const:`AF_PACKET`,
+ or :const:`AF_RDS`. The socket type should be :const:`SOCK_STREAM` (the
+ default), :const:`SOCK_DGRAM`, :const:`SOCK_RAW` or perhaps one of the other
+ ``SOCK_`` constants. The protocol number is usually zero and may be omitted
+ or in the case where the address family is :const:`AF_CAN` the protocol
+ should be one of :const:`CAN_RAW`, :const:`CAN_BCM` or :const:`CAN_ISOTP`.
If *fileno* is specified, the values for *family*, *type*, and *proto* are
auto-detected from the specified file descriptor. Auto-detection can be
diff --git a/Misc/NEWS.d/next/Documentation/2017-10-23-13-41-12.bpo-25041.iAo2gW.rst b/Misc/NEWS.d/next/Documentation/2017-10-23-13-41-12.bpo-25041.iAo2gW.rst
new file mode 100644
index 0000000..5bb6e25
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2017-10-23-13-41-12.bpo-25041.iAo2gW.rst
@@ -0,0 +1 @@
+Document ``AF_PACKET`` in the :mod:`socket` module.
diff --git a/Modules/socketmodule.c b/Modules/socketmodule.c
index f40bd89..eeade2e 100644
--- a/Modules/socketmodule.c
+++ b/Modules/socketmodule.c
@@ -1881,7 +1881,7 @@
const char *interfaceName;
int protoNumber;
int hatype = 0;
- int pkttype = 0;
+ int pkttype = PACKET_HOST;
Py_buffer haddr = {NULL, NULL};
if (!PyTuple_Check(args)) {
@@ -1912,7 +1912,7 @@
if (protoNumber < 0 || protoNumber > 0xffff) {
PyErr_SetString(
PyExc_OverflowError,
- "getsockaddrarg: protoNumber must be 0-65535.");
+ "getsockaddrarg: proto must be 0-65535.");
PyBuffer_Release(&haddr);
return 0;
}
@@ -2925,7 +2925,7 @@
\n\
Bind the socket to a local address. For IP sockets, the address is a\n\
pair (host, port); the host must refer to the local host. For raw packet\n\
-sockets the address is a tuple (ifname, proto [,pkttype [,hatype]])");
+sockets the address is a tuple (ifname, proto [,pkttype [,hatype [,addr]]])");
/* s.close() method.