Issue 25041: document AF_PACKET socket address format (original) (raw)
Created on 2015-09-09 13:07 by Tim.Tisdall, last changed 2022-04-11 14:58 by admin. This issue is now closed.
Messages (10)
Author: Tim Tisdall (Tim.Tisdall) *
Date: 2015-09-09 13:07
As mentioned in #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 )
Author: Tim Tisdall (Tim.Tisdall) *
Date: 2015-09-09 13:11
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.
Author: Camilla Montonen (Winterflower)
Date: 2015-10-29 22:09
Provided patch provides documentation for the AF_PACKET address_family.
Author: Berker Peksag (berker.peksag) * 
Date: 2015-10-30 07:17
Thanks! The patch looks good to me. I left a few minor comments on Rietveld: http://bugs.python.org/review/25041/
Author: Martin Panter (martin.panter) *
Date: 2015-10-31 04:02
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.
#947352 (Python 2.4), 8b3288f607e1: Support specifying hardware address, for sendto().
Here are some more things might be good to tease out:
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.
There is an error message mentioning “protoNumber” which could also be adjusted for consistency
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
proto is endian-corrected, in contrast with Linux’s version being in network byte-order
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.
addr has to be a bytes-like object
Packet support is specific to Linux, and may not be compiled in
Existence of PACKET and PACKET constants
socket.bind() doc string needs updating since revision c8ef864ba861 (missing fifth parameter, addr)
Author: Camilla Montonen (Winterflower)
Date: 2015-11-01 20:02
Thank you very much for the feedback, Martin and Berker! I'll start working on the revised patch.
Author: Cheryl Sabella (cheryl.sabella) *
Date: 2017-09-23 19:02
Hello Camilla,
Would you like to create a Github pull request for your patch?
Author: Benjamin Peterson (benjamin.peterson) *
Date: 2018-09-12 00:32
New changeset 731ff68eeef58babdf2b32dc9a73b141760c2be9 by Benjamin Peterson (Cheryl Sabella) in branch 'master': closes bpo-25041: Document AF_PACKET socket address format. (GH-4092) https://github.com/python/cpython/commit/731ff68eeef58babdf2b32dc9a73b141760c2be9
Author: Benjamin Peterson (benjamin.peterson) *
Date: 2018-09-12 01:46
New changeset cadb66e173ded86ebc85b54889db48f66e7af592 by Benjamin Peterson in branch '3.7': [3.7] closes bpo-25041: Document AF_PACKET socket address format. (GH-9207) https://github.com/python/cpython/commit/cadb66e173ded86ebc85b54889db48f66e7af592
Author: Benjamin Peterson (benjamin.peterson) *
Date: 2018-09-12 05:36
New changeset a00de685c11cf8bdca1f8efa7aab80552d80ddfb by Benjamin Peterson in branch '3.6': [3.6] closes bpo-25041: Document AF_PACKET socket address format. (GH-9209) https://github.com/python/cpython/commit/a00de685c11cf8bdca1f8efa7aab80552d80ddfb
History
Date
User
Action
Args
2022-04-11 14:58:20
admin
set
github: 69229
2018-09-12 05:36:14
benjamin.peterson
set
messages: +
2018-09-12 01:46:39
benjamin.peterson
set
messages: +
2018-09-12 00:36:08
benjamin.peterson
set
pull_requests: + <pull%5Frequest8643>
2018-09-12 00:33:38
benjamin.peterson
set
pull_requests: + <pull%5Frequest8641>
2018-09-12 00:32:18
benjamin.peterson
set
status: open -> closed
nosy: + benjamin.peterson
messages: +
resolution: fixed
stage: patch review -> resolved
2017-10-23 17:56:55
cheryl.sabella
set
stage: needs patch -> patch review
pull_requests: + <pull%5Frequest4062>
2017-09-24 02:41:24
Mariatta
set
stage: patch review -> needs patch
versions: + Python 3.7, - Python 3.4, Python 3.5
2017-09-23 19:02:39
cheryl.sabella
set
nosy: + cheryl.sabella
messages: +
2015-11-01 20:02:59
Winterflower
set
messages: +
2015-10-31 04:02:49
martin.panter
set
nosy: + martin.panter
messages: +
2015-10-30 07:17:05
berker.peksag
set
nosy: + berker.peksag
messages: +
stage: needs patch -> patch review
2015-10-29 22:09:31
Winterflower
set
files: + af_packet_doc.patch
nosy: + Winterflower
messages: +
keywords: + patch
2015-09-10 13:54:34
azsorkin
set
nosy: + azsorkin
2015-09-09 14:12:30
berker.peksag
set
keywords: + easy
stage: needs patch
2015-09-09 13:11:58
Tim.Tisdall
set
messages: +
2015-09-09 13:09:58
vstinner
set
nosy: + vstinner
2015-09-09 13:07:57
Tim.Tisdall
create