Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

document AF_PACKET socket address format #69229

Closed
TimTisdall mannequin opened this issue Sep 9, 2015 · 10 comments
Closed

document AF_PACKET socket address format #69229

TimTisdall mannequin opened this issue Sep 9, 2015 · 10 comments
Labels
3.7 (EOL) end of life docs Documentation in the Doc dir easy type-feature A feature request or enhancement

Comments

@TimTisdall
Copy link
Mannequin

TimTisdall mannequin commented Sep 9, 2015

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
    Copy link
    Mannequin Author

    TimTisdall mannequin commented Sep 9, 2015

    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 TimTisdall mannequin assigned docspython Sep 9, 2015
    @TimTisdall TimTisdall mannequin added docs Documentation in the Doc dir type-feature A feature request or enhancement labels Sep 9, 2015
    @TimTisdall
    Copy link
    Mannequin Author

    TimTisdall mannequin commented Sep 9, 2015

    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
    Copy link
    Mannequin

    Winterflower mannequin commented Oct 29, 2015

    Provided patch provides documentation for the AF_PACKET address_family.

    @berkerpeksag
    Copy link
    Member

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

    @vadmium
    Copy link
    Member

    vadmium commented Oct 31, 2015

    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
    Copy link
    Mannequin

    Winterflower mannequin commented Nov 1, 2015

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

    @csabella
    Copy link
    Contributor

    Hello Camilla,

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

    @Mariatta Mariatta added the 3.7 (EOL) end of life label Sep 24, 2017
    @benjaminp
    Copy link
    Contributor

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

    @benjaminp
    Copy link
    Contributor

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

    @benjaminp
    Copy link
    Contributor

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

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    3.7 (EOL) end of life docs Documentation in the Doc dir easy type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    5 participants
    @berkerpeksag @benjaminp @vadmium @Mariatta @csabella