tcgetwinsize(3): man page

[0.gangzta_gmail.com]

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.

[0.gangzta_gmail.com]

lib/libc/gen/tcsetwinsize.3

2 ↗

(On Diff #81231)

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

18 ↗

(On Diff #81231)

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

[0.gangzta_gmail.com]

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]

lib/libc/gen/tcsetwinsize.3

77 ↗

(On Diff #81231)

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]

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 ↗

(On Diff #81270)

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 ↗

(On Diff #81270)

New sentence should start at a new line.

79 ↗

(On Diff #81270)

New line.

84 ↗

(On Diff #81270)

New line.

91 ↗

(On Diff #81270)

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

107 ↗

(On Diff #81270)

Remove this as well.

150 ↗

(On Diff #81270)

These notes are not useful, remove.

[kib]

lib/libc/gen/tcsetwinsize.3

172 ↗

(On Diff #81270)

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]

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

[0.gangzta_gmail.com]

lib/libc/gen/tcsetwinsize.3

172 ↗

(On Diff #81270)

Aah. I understand.

[0.gangzta_gmail.com]

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]

lib/libc/gen/tcsetwinsize.3

56–58 ↗

(On Diff #81270)

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 ↗

(On Diff #81270)

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 ↗

(On Diff #81270)

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]

lib/libc/gen/tcsetwinsize.3

172 ↗

(On Diff #81270)

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]

lib/libc/gen/tcsetwinsize.3

172 ↗

(On Diff #81270)

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]

lib/libc/gen/tcsetwinsize.3

56–58 ↗

(On Diff #81270)

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]

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]

lib/libc/gen/tcgetwinsize.3

68

.Vt and not .Fa I believe

88

the .Dv SIGWINCH signal is sent ...

91

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

111

This can be typesetted as
.Rv -std

164

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

[0.gangzta_gmail.com]

lib/libc/gen/tcgetwinsize.3

111

Yes! Awesome!

[0.gangzta_gmail.com]

All the suggested updates have been made.