Kaydet (Commit) 731ff68e authored tarafından Cheryl Sabella's avatar Cheryl Sabella Kaydeden (comit) Benjamin Peterson

closes bpo-25041: Document AF_PACKET socket address format. (GH-4092)

üst b9bf9d02
...@@ -173,10 +173,25 @@ created. Socket addresses are represented as follows: ...@@ -173,10 +173,25 @@ created. Socket addresses are represented as follows:
.. versionadded:: 3.7 .. versionadded:: 3.7
- Certain other address families (:const:`AF_PACKET`, :const:`AF_CAN`) - :const:`AF_PACKET` is a low-level interface directly to network devices.
support specific representations. 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 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 program may show a nondeterministic behavior, as Python uses the first address
...@@ -376,6 +391,16 @@ Constants ...@@ -376,6 +391,16 @@ Constants
.. versionadded:: 3.7 .. 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 .. data:: AF_RDS
PF_RDS PF_RDS
SOL_RDS SOL_RDS
...@@ -469,12 +494,12 @@ The following functions all create :ref:`socket objects <socket-objects>`. ...@@ -469,12 +494,12 @@ The following functions all create :ref:`socket objects <socket-objects>`.
Create a new socket using the given address family, socket type and protocol Create a new socket using the given address family, socket type and protocol
number. The address family should be :const:`AF_INET` (the default), 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 :const:`AF_INET6`, :const:`AF_UNIX`, :const:`AF_CAN`, :const:`AF_PACKET`,
socket type should be :const:`SOCK_STREAM` (the default), or :const:`AF_RDS`. The socket type should be :const:`SOCK_STREAM` (the
:const:`SOCK_DGRAM`, :const:`SOCK_RAW` or perhaps one of the other ``SOCK_`` default), :const:`SOCK_DGRAM`, :const:`SOCK_RAW` or perhaps one of the other
constants. The protocol number is usually zero and may be omitted or in the ``SOCK_`` constants. The protocol number is usually zero and may be omitted
case where the address family is :const:`AF_CAN` the protocol should be one or in the case where the address family is :const:`AF_CAN` the protocol
of :const:`CAN_RAW`, :const:`CAN_BCM` or :const:`CAN_ISOTP` 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 If *fileno* is specified, the values for *family*, *type*, and *proto* are
auto-detected from the specified file descriptor. Auto-detection can be auto-detected from the specified file descriptor. Auto-detection can be
......
...@@ -1901,7 +1901,7 @@ getsockaddrarg(PySocketSockObject *s, PyObject *args, ...@@ -1901,7 +1901,7 @@ getsockaddrarg(PySocketSockObject *s, PyObject *args,
const char *interfaceName; const char *interfaceName;
int protoNumber; int protoNumber;
int hatype = 0; int hatype = 0;
int pkttype = 0; int pkttype = PACKET_HOST;
Py_buffer haddr = {NULL, NULL}; Py_buffer haddr = {NULL, NULL};
if (!PyTuple_Check(args)) { if (!PyTuple_Check(args)) {
...@@ -1943,7 +1943,7 @@ getsockaddrarg(PySocketSockObject *s, PyObject *args, ...@@ -1943,7 +1943,7 @@ getsockaddrarg(PySocketSockObject *s, PyObject *args,
if (protoNumber < 0 || protoNumber > 0xffff) { if (protoNumber < 0 || protoNumber > 0xffff) {
PyErr_Format( PyErr_Format(
PyExc_OverflowError, PyExc_OverflowError,
"%s(): protoNumber must be 0-65535.", caller); "%s(): proto must be 0-65535.", caller);
PyBuffer_Release(&haddr); PyBuffer_Release(&haddr);
return 0; return 0;
} }
...@@ -2979,7 +2979,7 @@ PyDoc_STRVAR(bind_doc, ...@@ -2979,7 +2979,7 @@ PyDoc_STRVAR(bind_doc,
\n\ \n\
Bind the socket to a local address. For IP sockets, the address is a\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\ 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. /* s.close() method.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment