document AF_PACKET socket address format

[TimTisdall]

BPO	25041
Nosy	@vstinner, @benjaminp, @berkerpeksag, @vadmium, @csabella
PRs	bpo-25041: Document AF_PACKET socket address format  #4092 [3.7] closes bpo-25041: Document AF_PACKET socket address format. #9207 [3.6] closes bpo-25041: Document AF_PACKET socket address format. #9209
Files	af_packet_doc.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2018-09-12.00:32:18.862>
created_at = <Date 2015-09-09.13:07:57.371>
labels = ['easy', 'type-feature', '3.7', 'docs']
title = 'document AF_PACKET socket address format'
updated_at = <Date 2018-09-12.05:36:14.039>
user = 'https://bugs.python.org/TimTisdall'

bugs.python.org fields:

activity = <Date 2018-09-12.05:36:14.039>
actor = 'benjamin.peterson'
assignee = 'docs@python'
closed = True
closed_date = <Date 2018-09-12.00:32:18.862>
closer = 'benjamin.peterson'
components = ['Documentation']
creation = <Date 2015-09-09.13:07:57.371>
creator = 'Tim.Tisdall'
dependencies = []
files = ['40898']
hgrepos = []
issue_num = 25041
keywords = ['patch', 'easy']
message_count = 10.0
messages = ['250306', '250307', '253696', '253722', '253773', '253871', '302797', '325108', '325112', '325122']
nosy_count = 9.0
nosy_names = ['vstinner', 'benjamin.peterson', 'docs@python', 'berker.peksag', 'martin.panter', 'Tim.Tisdall', 'azsorkin', 'Winterflower', 'cheryl.sabella']
pr_nums = ['4092', '9207', '9209']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue25041'
versions = ['Python 3.6', 'Python 3.7']

[TimTisdall]

As mentioned in bpo-24984, I'm making another issue to document the address format for AF_PACKET. In this case there's already documentation in Modules/socketmodule.c that says:

• an AF_PACKET socket address is a tuple containing a string
  specifying the ethernet interface and an integer specifying
  the Ethernet protocol number to be received. For example:
  ("eth0",0x1234). Optional 3rd,4th,5th elements in the tuple
  specify packet-type and ha-type/addr.

But nothing has been added to Doc/library/socket.rst .

The documentation needs to be confirmed with the code. (It probably should be altered somewhat to state how you "specify packet-type and ha-type/addr"... and maybe what a "ha-type/addr" is... A quick Google search found this very useful reference: https://books.google.ca/books?id=Chr1NDlUcI8C&pg=PA472&ots=OCEwyjdXJo&sig=PuNG72WIvv4-A924f9MvzPtgQDc&hl=en&sa=X&ved=0CE8Q6AEwCGoVChMI6IiTyoDqxwIVCTs-Ch3bCAXy#v=onepage&q&f=false )

[TimTisdall]

Right now the docs say "Certain other address families (:const:`AF_PACKET`, :const:`AF_CAN`) support specific representations.".

I was going to create a separate issue for AF_CAN, but it seems that it's already documented... When documentation is added for AF_PACKET, please remove the above mentioned line entirely as AF_CAN is already documented.

[Winterflower]

Provided patch provides documentation for the AF_PACKET address_family.

[berkerpeksag]

Thanks! The patch looks good to me. I left a few minor comments on Rietveld: http://bugs.python.org/review/25041/

[vadmium]

Quickly looking through the history (annotate function on Mercurial web frontend):

• Revisions 3d4a7cd0bf17, c8ef864ba861 (2001): AF_PACKET support added on Linux. Partially documented in C comment and socket.bind() docstring. AF/PF_PACKET, PACKET_* constants also added.

• bpo-947352 (Python 2.4), 8b3288f607e1: Support specifying hardware address, for sendto().

Here are some more things might be good to tease out:

1. Please don’t invent new parameter names without a good reason. I suggest (ifname, proto, pkttype, hatype, addr). These are already used in the bind() doc string, most are consistent with Linux’s struct sockaddr_ll fields, and “proto” is consistent with Python’s socket() constructor.

2. There is an error message mentioning “protoNumber” which could also be adjusted for consistency

3. When Python generates the ifname string, it uses the empty string for ifindex zero (matching any interface), although it does not look like parsing this back is supported

4. proto is endian-corrected, in contrast with Linux’s version being in network byte-order

5. Default pkttype is zero. This is equal to PACKET_HOST, so could be useful. Might also be worth changing the source code to explicitly use PACKET_HOST.

6. addr has to be a bytes-like object

7. Packet support is specific to Linux, and may not be compiled in

8. Existence of *PACKET and PACKET* constants

9. socket.bind() doc string needs updating since revision c8ef864ba861 (missing fifth parameter, addr)

[Winterflower]

Thank you very much for the feedback, Martin and Berker!
I'll start working on the revised patch.

[csabella]

Hello Camilla,

Would you like to create a Github pull request for your patch?

[benjaminp]

New changeset 731ff68 by Benjamin Peterson (Cheryl Sabella) in branch 'master':
closes bpo-25041: Document AF_PACKET socket address format. (GH-4092)
731ff68

[benjaminp]

New changeset cadb66e by Benjamin Peterson in branch '3.7':
[3.7] closes bpo-25041: Document AF_PACKET socket address format. (GH-9207)
cadb66e