Bug 257964

Summary:

snp(4) manual page is out of sync with the device implementation

Product:

Documentation

Reporter:

Bertrand Petit <bsdpr>

Component:

Manual Pages

Assignee:

Konstantin Belousov <kib>

Status:

Closed FIXED

Severity:

Affects Only Me

CC:

bsdpr, doc, felix.the.red, kib

Priority:

---

Version:

Latest

Hardware:

Any

OS:

Any

Attachments:

Description	Flags
snp(4) patch	felix.the.red: maintainer-approval? (felix.the.red)

Description Bertrand Petit 2021-08-20 09:19:02 UTC

This bug report about the snp(4) manual page is a follow-up to a question I asked in freebsd-hackers: https://lists.freebsd.org/archives/freebsd-hackers/2021-August/000216.html

1. The description of the device is inaccurate: in "allows users to attach to any tty and watch activities on it", the plural on "activities" led me to think that we could snoop on bidirectional traffic. Instead it should be made clear that we can only snoop on egress streams, ie. data originating from the host.

2. Special values mentioned for the FIONREAD ioctl() are no longer used, in snp.c none of those symbols are actually present. They should be removed from the manual page as well as "This version of snp does not return proper error codes when calling FIONREAD" in the BUGS section. These symbols could however still be mentioned as being obsolete in the HISTORY section.

3. Today, disappearance, closure and detachment of the snooped device are now signaled by an EIO return on read() and by an EIO or ENXIO return on write(). This should be documented.

4. There is no handling of overflow as it used to be. Quoting the source code: "Right now we don't support any form of flow control". This should be documented.

Comment 1 Felix Johnson 2021-10-01 07:56:07 UTC

Created attachment 228305 [details]
snp(4) patch

Document that:
 - snp(4) can only handle egress streams (ones that originate from the host)
 - The FIONREAD ioctl no longer returns special values,
   move them to the HISTORY section
 - Device disappearance, closure, or detachment will result
   in EIO or ENXIO from read(2) or write(2) calls
 - Flow control is not supported, under BUGS

Comment 2 Konstantin Belousov freebsd_committer

2022-09-24 20:27:53 UTC

See https://reviews.freebsd.org/D36690 WRT FIONREAD

Comment 3 commit-hook freebsd_committer

2022-09-25 20:37:13 UTC

A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/src/commit/?id=bb4be76cf358246ef04ea8a67f38ff2a25b6c580

commit bb4be76cf358246ef04ea8a67f38ff2a25b6c580
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2022-09-24 20:23:31 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2022-09-25 20:36:16 +0000

    snp(4): properly report detached/revoked ttys

    PR:     257964
    Reported by:    Bertrand Petit <bsdpr@phoe.frmug.org>
    Reviewed by:    imp, markj
    Sponsored by:   The FreeBSD Foundation
    MFC after:      1 week
    Differential revision:  https://reviews.freebsd.org/D36690

 share/man/man4/snp.4 | 8 ++------
 sys/dev/snp/snp.c    | 7 +++++--
 2 files changed, 7 insertions(+), 8 deletions(-)

Comment 4 commit-hook freebsd_committer

2022-09-25 20:37:15 UTC

A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/src/commit/?id=550e01c552474babae468011191ecc5130cc153e

commit 550e01c552474babae468011191ecc5130cc153e
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2022-09-25 11:34:17 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2022-09-25 20:36:16 +0000

    snp(4): implement detach

    PR:     257964
    Reported by:    Bertrand Petit <bsdpr@phoe.frmug.org>
    Reviewed by:    imp, markj
    Sponsored by:   The FreeBSD Foundation
    MFC after:      1 week
    Differential revision:  https://reviews.freebsd.org/D36690

 share/man/man4/snp.4 |  6 ------
 sys/dev/snp/snp.c    | 15 +++++++++++++--
 2 files changed, 13 insertions(+), 8 deletions(-)

Comment 5 commit-hook freebsd_committer

2022-10-02 00:53:14 UTC

A commit in branch stable/13 references this bug:

URL: https://cgit.FreeBSD.org/src/commit/?id=ff1993be35d643a55c00d301628bfe1bfaeeffc4

commit ff1993be35d643a55c00d301628bfe1bfaeeffc4
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2022-09-25 11:34:17 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2022-10-02 00:51:47 +0000

    snp(4): implement detach

    PR:     257964

    (cherry picked from commit 550e01c552474babae468011191ecc5130cc153e)

 share/man/man4/snp.4 |  6 ------
 sys/dev/snp/snp.c    | 15 +++++++++++++--
 2 files changed, 13 insertions(+), 8 deletions(-)

Comment 6 commit-hook freebsd_committer

2022-10-02 00:53:16 UTC

A commit in branch stable/13 references this bug:

URL: https://cgit.FreeBSD.org/src/commit/?id=40860e6bf2221efb3840b380d6b5d6f3f768a633

commit 40860e6bf2221efb3840b380d6b5d6f3f768a633
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2022-09-24 20:23:31 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2022-10-02 00:51:47 +0000

    snp(4): properly report detached/revoked ttys

    PR:     257964

    (cherry picked from commit bb4be76cf358246ef04ea8a67f38ff2a25b6c580)

 share/man/man4/snp.4 | 8 ++------
 sys/dev/snp/snp.c    | 7 +++++--
 2 files changed, 7 insertions(+), 8 deletions(-)

Comment 7 Mark Linimon freebsd_committer

2024-01-10 05:16:36 UTC

^Triage: assign to committer that resolved.