Page MenuHomeFreeBSD
Differential D27787

tcgetwinsize(3): man page
ClosedPublic
Actions

Authored by 0.gangzta_gmail.com on Dec 27 2020, 8:26 PM.
Tags
None
Referenced Files
F161285672: D27787.id81270.diff
Thu, Jul 2, 11:06 AM
Unknown Object (File)
Tue, Jun 30, 10:51 PM
Unknown Object (File)
Tue, Jun 30, 3:56 PM
Unknown Object (File)
Tue, Jun 30, 12:16 PM
Unknown Object (File)
Fri, Jun 26, 6:12 PM
Unknown Object (File)
Sun, Jun 21, 1:03 PM
Unknown Object (File)
Fri, Jun 19, 2:34 AM
Unknown Object (File)
Mon, Jun 8, 12:07 AM
View All Files
Subscribers
jilles

Details

Reviewers
kib
yuripv
oliver.pntr-gmail.com
Group Reviewers
manpages
Commits
rG4e0c81c5fafb: tcgetwinsize(3): provide man page
Summary

The current POSIX.1-202x draft (1.1) was used as source material.

Corresponding NetBSD manpage for comparison: https://man.netbsd.org/tcgetwinsize.3

Corresponding Bugzilla entry: https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=251868

If this patch is accepted, then please use "soumendraganguly AT gmail DOTCOM" for submitter email address in the commit.

Diff Detail

Lint
Lint Skipped
Unit
Tests Skipped

Event Timeline

0.gangzta_gmail.com requested review of this revision.Dec 27 2020, 8:26 PM
0.gangzta_gmail.com created this revision.
cem removed a reviewer: cem.Dec 27 2020, 9:55 PM
0.gangzta_gmail.com edited the summary of this revision. (Show Details)Dec 28 2020, 1:52 AM
0.gangzta_gmail.com edited the summary of this revision. (Show Details)Dec 28 2020, 1:56 AM
0.gangzta_gmail.com retitled this revision from Manual page for the new tcgetwinsize() and tcsetwinsize() functions to tcgetwinsize(3): man page.Dec 28 2020, 2:04 AM
0.gangzta_gmail.com edited the summary of this revision. (Show Details)
0.gangzta_gmail.com edited the summary of this revision. (Show Details)Dec 28 2020, 4:36 AM
0.gangzta_gmail.com added inline comments.Dec 28 2020, 4:49 AM
lib/libc/gen/tcsetwinsize.3
3

Copyright acceptable? This is the first manual page/nroff document I have ever written. Criticism, however harsh, is welcomed.

19

Should I put something in place of [your name]? I saw other files where it was left like this.

0.gangzta_gmail.com edited the summary of this revision. (Show Details)Dec 28 2020, 5:16 PM
0.gangzta_gmail.com updated this revision to Diff 81270.Dec 28 2020, 5:39 PM

Added the fact that SIGWINCH is only sent to those processes in the foreground process group that have the terminal as their controlling terminal.

0.gangzta_gmail.com added inline comments.Dec 28 2020, 5:44 PM
lib/libc/gen/tcsetwinsize.3
78

Note for reference: the POSIX manpage says "If the terminal size was changed succesfully, a SIGWINCH shall be delivered to the foreground process group associated with the terminal." The source of tty_set_winsize() and of tty_signal_pgrp() in sys/kern/tty.c was used as justification for this line. However, it should be noted that the 3rd argument in the pgsignal(tp->t_pgrp, sig, 1, &ksi); call in the definition of tty_signal_pgrp() results in SIGWINCH only being sent to those members of the foreground process group that have a controlling terminal.

kib added a comment.Dec 28 2020, 7:18 PM

You should:

  1. note that the winsize structure content is unused by kernel
  2. cross-reference this man page from termios(4)

It is strange that the file is named tcsetwinsize.3 while the first function (correctly, by alphabetical order) is tcgetwinsize. I suggest to rename source to tcgetwinsize.3.

lib/libc/gen/tcsetwinsize.3
4

This is pointless.

Also, if you did took some portions of the text from the POSIX draft, look how Open Group is attributed in copyright block. As a random example, look at lib/libc/sys/mq_getattr.2

72

New sentence should start at a new line.

79

New line.

84

New line.

91

I suggest to end there. and remove 'as follows' and the half-done code example.

107

Remove this as well.

150

These notes are not useful, remove.

kib added a reviewer: manpages.Dec 28 2020, 7:19 PM
kib added inline comments.
lib/libc/gen/tcsetwinsize.3
172

I am sure that there is no 'issue 8' of posix. Issue 8 is for 'base specification', while POSIX is p1003.1-<year>.

0.gangzta_gmail.com added a comment.Dec 28 2020, 8:27 PM

@kib All of your comments are very helpful. I am working on the improvements now.

0.gangzta_gmail.com added inline comments.Dec 28 2020, 8:29 PM
lib/libc/gen/tcsetwinsize.3
172

Aah. I understand.

0.gangzta_gmail.com added a comment.Dec 28 2020, 8:32 PM
In D27787#621465, @kib wrote:

It is strange that the file is named tcsetwinsize.3 while the first function (correctly, by alphabetical order) is tcgetwinsize. I suggest to rename source to tcgetwinsize.3.

That is what I was thinking. I was imitating the already existing tcsetattr.3. cfgetispeed() is the first function in that file if we go by dictionary/alphabetical order.

jilles added a subscriber: jilles.Dec 28 2020, 9:39 PM
jilles added inline comments.
lib/libc/gen/tcsetwinsize.3
56–58

In FreeBSD, these calls also work on pseudo-terminal masters, which are not terminals. This is useful for applications like xterm. Do we want to mention something about this?

141–148

This is effectively a promise that a future version will not need to touch the structure in userland (for example to convert an old version of the structure to or from the kernel's version). This is probably OK, but I don't think it is particularly useful for applications to rely on.

172

Issue 8 has not been released yet, so the year cannot be known for sure. It is also still possible (but unlikely) for the specification of the functions to change or to be removed entirely.

0.gangzta_gmail.com added inline comments.Dec 28 2020, 9:40 PM
lib/libc/gen/tcsetwinsize.3
172

I have verified that you are correct. The NetBSD man page has incorrect wording. I will inform them about this once we are done.

0.gangzta_gmail.com added inline comments.Dec 28 2020, 9:46 PM
lib/libc/gen/tcsetwinsize.3
172

I am sorry; that comment was a reply to @kib's earlier comment. My browser had not loaded your comment yet. Is it okay if I write P1003.1-202x then? That is what the draft pdf says.

0.gangzta_gmail.com added inline comments.Dec 28 2020, 9:57 PM
lib/libc/gen/tcsetwinsize.3
56–58

While pseudo-terminal masters are not required to be terminals, IIRC, calling isatty on pty masters on FreeBSD and some other OSes actually does return 1... so maybe they are implemented as terminals? Please help if I am understanding something incorrectly.

0.gangzta_gmail.com updated this revision to Diff 81279.Dec 28 2020, 10:13 PM

Made all the requested updates. Used terminology from https://standards.ieee.org/project/1003_1.html to justify writing .St -p1003.1 Base Specifications, Issue 8.

kib added inline comments.Jan 1 2021, 4:15 AM
lib/libc/gen/tcgetwinsize.3
67 ↗(On Diff #81279)

.Vt and not .Fa I believe

87 ↗(On Diff #81279)

the .Dv SIGWINCH signal is sent ...

90 ↗(On Diff #81279)

I do not think this reference is useful, remove the sentence.

110 ↗(On Diff #81279)

This can be typesetted as
.Rv -std

163 ↗(On Diff #81279)

Usually we note that some members are 'FreeBSD extensions' instead of saying that standard does not specify something.

0.gangzta_gmail.com added inline comments.Jan 1 2021, 12:47 PM
lib/libc/gen/tcgetwinsize.3
110 ↗(On Diff #81279)

Yes! Awesome!

0.gangzta_gmail.com updated this revision to Diff 81467.Jan 1 2021, 12:52 PM

All the suggested updates have been made.

This revision was not accepted when it landed; it landed in state Needs Review.Jan 2 2021, 2:44 AM
Closed by commit rG4e0c81c5fafb: tcgetwinsize(3): provide man page (authored by kib). · Explain Why
This revision was automatically updated to reflect the committed changes.
kib added a commit: rG4e0c81c5fafb: tcgetwinsize(3): provide man page.

Revision Contents
Changeset List

PathSize
lib/
libc/
gen/
2 lines
178 lines

Diff 81270

View Options

lib/libc/gen/Makefile.inc

Loading...
View Options

lib/libc/gen/tcsetwinsize.3

Loading...