[3.6] closes bpo-25041: Document AF_PACKET socket address format. (GH… · python/cpython@a00de68 (original) (raw)

`@@ -156,10 +156,25 @@ created. Socket addresses are represented as follows:

156

157

` .. versionadded:: 3.6

158

159

`` -

Certain other address families (:const:AF_PACKET, :const:AF_CAN)

160

support specific representations.

161

-

162

.. XXX document them!

159

`` +

:const:AF_PACKET is a low-level interface directly to network devices.

160

The packets are represented by the tuple

161


 ``(ifname, proto[, pkttype[, hatype[, addr]]])`` where:

162

+

163

ifname - String specifying the device name.

164

proto - An in network-byte-order integer specifying the Ethernet

165

protocol number.

166

pkttype - Optional integer specifying the packet type:

167

+

168


 - ``PACKET_HOST`` (the default) - Packet addressed to the local host.

169


 - ``PACKET_BROADCAST`` - Physical-layer broadcast packet.

170


 - ``PACKET_MULTIHOST`` - Packet sent to a physical-layer multicast address.

171


 - ``PACKET_OTHERHOST`` - Packet to some other host that has been caught by

172

a device driver in promiscuous mode.

173


 - ``PACKET_OUTGOING`` - Packet originating from the local host that is

174

looped back to a packet socket.

175

hatype - Optional integer specifying the ARP hardware address type.

176

addr - Optional bytes-like object specifying the hardware physical

177

address, whose interpretation depends on the device.

163

178

164

179

`If you use a hostname in the host portion of IPv4/v6 socket address, the

165

180

`program may show a nondeterministic behavior, as Python uses the first address

`@@ -343,6 +358,17 @@ Constants

343

358

344

359

` .. versionadded:: 3.5

345

360

361

+

362

.. data:: AF_PACKET

363

PF_PACKET

364

PACKET_*

365

+

366

Many constants of these forms, documented in the Linux documentation, are

367

also defined in the socket module.

368

+

369

Availability: Linux >= 2.2.

370

+

371

+

346

372

`.. data:: AF_RDS

347

373

` PF_RDS

348

374

` SOL_RDS

`` @@ -424,16 +450,16 @@ The following functions all create :ref:socket objects <socket-objects>.

424

450

425

451

` Create a new socket using the given address family, socket type and protocol

426

452

`` number. The address family should be :const:AF_INET (the default),

427

`` -

:const:AF_INET6, :const:AF_UNIX, :const:AF_CAN or :const:AF_RDS. The

428

`` -

socket type should be :const:SOCK_STREAM (the default),

429


:const:`SOCK_DGRAM`, :const:`SOCK_RAW` or perhaps one of the other ``SOCK_``

430

constants. The protocol number is usually zero and may be omitted or in the

431

`` -

case where the address family is :const:AF_CAN the protocol should be one

432

`` -

of :const:CAN_RAW or :const:CAN_BCM. If fileno is specified, the other

433

arguments are ignored, causing the socket with the specified file descriptor

434

`` -

to return. Unlike :func:socket.fromfd, fileno will return the same

435

socket and not a duplicate. This may help close a detached socket using

436

`` -

:meth:socket.close().

453

`` +

:const:AF_INET6, :const:AF_UNIX, :const:AF_CAN, :const:AF_PACKET, or

454

`` +

:const:AF_RDS. The socket type should be :const:SOCK_STREAM (the

455

`` +

default), :const:SOCK_DGRAM, :const:SOCK_RAW or perhaps one of the other

456


``SOCK_`` constants. The protocol number is usually zero and may be omitted

457

`` +

or in the case where the address family is :const:AF_CAN the protocol

458

`` +

should be one of :const:CAN_RAW or :const:CAN_BCM. If fileno is

459

specified, the other arguments are ignored, causing the socket with the

460

`` +

specified file descriptor to return. Unlike :func:socket.fromfd, fileno

461

will return the same socket and not a duplicate. This may help close a

462

`` +

detached socket using :meth:socket.close().

437

463

438

464

`` The newly created socket is :ref:non-inheritable <fd_inheritance>.

439

465