diff options
author | Cheryl Sabella <cheryl.sabella@gmail.com> | 2018-09-11 20:32:15 -0400 |
---|---|---|
committer | Benjamin Peterson <benjamin@python.org> | 2018-09-11 17:35:23 -0700 |
commit | d141bab2080d5dcb404beacb5c1a4e78f106bf8e (patch) | |
tree | 1339b3acd231d87aa9e15cc366243fddff969c41 | |
parent | 31912b43c903aafad09350899ed6a9dec7c43421 (diff) | |
download | cpython-git-backport-731ff68-3.6.tar.gz |
[3.6] closes bpo-25041: Document AF_PACKET socket address format. (GH-4092).backport-731ff68-3.6
(cherry picked from commit 731ff68eeef58babdf2b32dc9a73b141760c2be9)
Co-authored-by: Cheryl Sabella <cheryl.sabella@gmail.com>
-rw-r--r-- | Doc/library/socket.rst | 54 | ||||
-rw-r--r-- | Misc/NEWS.d/next/Documentation/2017-10-23-13-41-12.bpo-25041.iAo2gW.rst | 1 | ||||
-rw-r--r-- | Modules/socketmodule.c | 6 |
3 files changed, 44 insertions, 17 deletions
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 974df4c6d9..f4e5af9d5e 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -156,10 +156,25 @@ created. Socket addresses are represented as follows: .. versionadded:: 3.6 -- Certain other address families (:const:`AF_PACKET`, :const:`AF_CAN`) - support specific representations. - - .. XXX document them! +- :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: + + - *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 @@ -343,6 +358,17 @@ Constants .. versionadded:: 3.5 + +.. 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 @@ -424,16 +450,16 @@ The following functions all create :ref:`socket objects <socket-objects>`. 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` or :const:`CAN_BCM`. If *fileno* is specified, the other - arguments are ignored, causing the socket with the specified file descriptor - to return. Unlike :func:`socket.fromfd`, *fileno* will return the same - socket and not a duplicate. This may help close a detached socket using - :meth:`socket.close()`. + :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` or :const:`CAN_BCM`. If *fileno* is + specified, the other arguments are ignored, causing the socket with the + specified file descriptor to return. Unlike :func:`socket.fromfd`, *fileno* + will return the same socket and not a duplicate. This may help close a + detached socket using :meth:`socket.close()`. The newly created socket is :ref:`non-inheritable <fd_inheritance>`. 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 0000000000..5bb6e25db9 --- /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 ff73a3fbfa..ed31667402 100644 --- a/Modules/socketmodule.c +++ b/Modules/socketmodule.c @@ -1834,7 +1834,7 @@ getsockaddrarg(PySocketSockObject *s, PyObject *args, const char *interfaceName; int protoNumber; int hatype = 0; - int pkttype = 0; + int pkttype = PACKET_HOST; Py_buffer haddr = {NULL, NULL}; if (!PyTuple_Check(args)) { @@ -1865,7 +1865,7 @@ getsockaddrarg(PySocketSockObject *s, PyObject *args, 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; } @@ -2742,7 +2742,7 @@ PyDoc_STRVAR(bind_doc, \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. |