summaryrefslogtreecommitdiffstats
Commit message (Collapse)AuthorAgeLines
* man*/: ffix (MR.sed)MRG. Branden Robinson2024-01-15-15569/+15732
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Use the man(7) macro `MR`, new to groff 1.23.0, instead of font style alternation macros to mark up man-page cross references. Hi Alex, All past efforts at submitting a patch for this have met with vger's wrath and rage--even a diffstat is too much for it tolerate. For those who don't remember what this proposal is meant to achieve, here's a backgrounder from October[0]. groff 1.23.0 has been out for over six months[1] and every major GNU/Linux distribution, plus several non-major ones, is shipping it.[2] I'm attaching two scripts, "MR-migrate.sh" and "MR.sed". Drop them in the directory of your man-pages checkout, and run the first with a POSIX shell. The migration script doesn't just alter the pages; it also generates "before.txt" and "after.txt" files containing the man page contents rendered as (UTF-8) plain text to verify that no changes to page content (apart from font style change to man page cross references attendant to the use of a new macro, which is user-configurable[3]) occur. I get the following output: $ sh ./MR-migrate.sh man4/console_codes.4:324: warning: table wider than line length minus indentation man5/proc_pid_smaps.5:88: warning: table wider than line length minus indentation troff:man7/ascii.7:28: warning: cannot select font 'CW' man4/console_codes.4:324: warning: table wider than line length minus indentation man5/proc_pid_smaps.5:88: warning: table wider than line length minus indentation troff:man7/ascii.7:28: warning: cannot select font 'CW' SAME Thanks again to Brian Inglis for reminding me not to update externally generated/sourced pages (bpf-helpers and Paul Eggert's tz project). Regards, Branden [0] https://lore.kernel.org/linux-man/20231025185341.mqvn7qlm3iby4zgm@illithid/ [1] https://lists.gnu.org/archive/html/info-gnu/2023-07/msg00001.html [2] https://repology.org/project/groff/versions [3] You can of course find out how in groff_man(7). $ cat MR-migrate.sh #!/bin/sh set -e groff_cmd="groff -t -dAD=l -rHY=0 -m andoc -T utf8 -P -cbou" pages=$(grep -L '^\.so ' man*/* \ | grep -Ev '(tzfile|tzselect|zdump|zic|time2posix|bpf-helpers)' \ | sort) $groff_cmd $pages > before.txt sed -i -f MR.sed $pages $groff_cmd $pages > after.txt cmp before.txt after.txt && echo SAME # git co . # to revert ############## $ cat MR.sed # Handle simplest cases: ".BR foo (1)" and ".IR foo (1)". s/^.[BI]R \(\\%\)*\([.@_[:alnum:]\\-]\+\) (\([1-9a-z]\+\))$/.MR \2 \3/ # Handle case: trailing punctuation, as in ".IR foo (1),". s/^.[BI]R \(\\%\)*\([.@_[:alnum:]\\-]\+\) (\([1-9a-z]\+\))\([^[:space:]]\+\)$/.MR \2 \3 \4/ # Handle case: leading punctuation, as in ".RI ( foo (1)". s/^.R[BI] \(\\%\)*\([^[:space:]]\+\) \([.@_[:alnum:]\\-]\+\) (\([1-9a-z]\+\))\([^[:space:]]\+\)$/\\%\2\\c\n.MR \3 \4 \5/ # Handle case: 3rd+ arguments or trailing comments. This case is rare # and will require manual fixup if there are 4+ arguments to MR. Use # groff -man -rCHECKSTYLE=1 to have them automatically reported. s/^.[BI]R \(\\%\)*\([.@_[:alnum:]\\-]\+\) (\([1-8a-z]\+\))\( .*\)/.MR \2 \3\4/ Link: <https://lore.kernel.org/linux-man/20240114154225.5tyuiqrgwyltqmj3@illithid/T/#u> Signed-off-by: "G. Branden Robinson" <g.branden.robinson@gmail.com> Cc: Jakub Wilk <jwilk@jwilk.net> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* locale.5: tfixG. Branden Robinson2024-01-15-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | ...that proved surprisingly tough to troubleshoot. I got the following output from my working copy. grotty:...:(man5/locale.5):32291: error: output above first line discarded grotty:...:(man5/locale.5):32291: error: output above first line discarded grotty:...:(man5/locale.5):32291: error: output above first line discarded grotty:...:(man5/locale.5):32291: error: output above first line discarded grotty:...:(man5/locale.5):32291: error: output above first line discarded grotty:...:(man5/locale.5):32291: error: output above first line discarded grotty:...:(man5/locale.5):32291: error: output above first line discarded grotty:...:(man5/locale.5):32291: error: output above first line discarded grotty:...:(man5/locale.5):32291: error: output above first line discarded grotty:...:(man5/locale.5):32292: error: output above first line discarded grotty:...:(man5/locale.5):32294: error: output above first line discarded grotty:...:(man5/locale.5):32294: error: output above first line discarded grotty:...:(man5/locale.5):32294: error: output above first line discarded grotty:...:(man5/locale.5):32294: error: output above first line discarded grotty:...:(man5/locale.5):32294: error: output above first line discarded `\r` is a perfectly legal *roff escape sequence, but one generally never sees it in man pages. In that case, the input line in question was at the top of the "page" in continuous rendering mode, and so the attempt at a reverse vertical motion did indeed put the drawing position above the top of the page. grepping reveals no other occurrences of '\r' in the man-pages corpus. Signed-off-by: "G. Branden Robinson" <g.branden.robinson@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* cpuid.4: Note which CPUs don't support CPUID and what happensнаб2024-01-05-1/+3
| | | | | | | | | | | | | | | | "Early 486" comes from an uncited wikipedia table, added in <https://en.wikipedia.org/w/index.php?title=CPUID&diff=prev&oldid=592047209> <https://en.wikipedia.org/w/index.php?title=CPUID&diff=prev&oldid=592047978> but I spot-checked the rest of the table accurate to CPUs in my house (the oldest of which is an original Celeron, so no 486), and "early 486" is better than "early x86" which can mean anything. This does leave earlier x86 unmentioned, but Linux hasn't targeted those in over a decade, so they're out of scope anyway. Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* sched_getcpu.3: tfixAlejandro Colomar2024-01-01-1/+1
| | | | | | Fixes: 2b65a83f2983 ("Documents sched_getcpu(3), a wrapper for getcpu(2), provided since glibc 2.6.") Reported-by: Shahab Ouraie <shahabouraie@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* faccessat(2), utimensat(2): Document AT_EMPTY_PATH flagRenzo Davoli2024-01-01-2/+44
| | | | | | | | | | | | | utimensat() and faccessat() support the flag AT_EMPTY_PATH since Linux 5.8. (actually Linux 5.8 added faccessat2(): glibc wrapper for faccessat() uses faccessat2(), and faccessat2() does support AT_EMPTY_PATH). Reuse the standard text used in many other -at manual pages. Signed-off-by: Renzo Davoli <renzo@cs.unibo.it> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* fopencookie.3, stdio.3: wfixнаб2023-12-29-2/+2
| | | | | | Suggested-by: Alejandro Colomar <alx@kernel.org> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* stdio.3: Note down fmemopen(3), fopencookie(3), and open_[w]memstream(3)наб2023-12-29-0/+12
| | | | | | | | | I was looking for fmemopen() to remember I was actually looking for open_memstream(), and it was much more difficult than it ought to've been. Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* open_memstream.3: ffixнаб2023-12-28-1/+1
| | | | | Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* CONTRIBUTING: Reduce strength of encouragementAlejandro Colomar2023-12-28-2/+2
| | | | | | | | | That paragraph may be confusing to those who don't know about PGP, so reduce strength of encouragement. But to those that know about PGP, and know how to use it, please, please use it. Suggested-by: "G. Branden Robinson" <branden@debian.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* CONTRIBUTING: Accept patches in attachmentsAlejandro Colomar2023-12-22-3/+1
| | | | | | | | I use mutt(1), which works fine with patches as attachments, and the mailing list archives also work fine with attachments. Let's accept attachments. Signed-off-by: Alejandro Colomar <alx@kernel.org>
* CONTRIBUTING: The Majordomo has been firedAlejandro Colomar2023-12-22-13/+3
| | | | | | | | The infrastructure of the list was recently modified. Now, all the information to subscribe, unsubscribe, or other actions, are in <https://subspace.kernel.org/vger.kernel.org.html>. Signed-off-by: Alejandro Colomar <alx@kernel.org>
* swapon.2: MAX_SWAPFILES: Clarify limit after decreaseYang Xu2023-12-22-2/+2
| | | | | Signed-off-by: Yang Xu <xuyang2018.jy@fujitsu.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* ioctl_console.2: Document new CAP_SYS_ADMIN restrictions (since Linux 6.7)Günther Noack2023-12-21-0/+12
| | | | | | | | | | | Since Linux commit 8d1b43f6a6df7bce ("tty: Restrict access to TIOCLINUX' copy-and-paste subcommands"), the TIOCL_SETSEL, TIOCL_PASTESEL and TIOCL_SELLOADLUT subcommands require CAP_SYS_ADMIN. Cc: Hanno Böck <hanno@hboeck.de> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Günther Noack <gnoack@google.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* sendfile.2: Pull in_fd type requirements up to 6.7наб2023-12-21-1/+10
| | | | | | | | | | | | | | But this does mean that since 5.12, it supports (5.12 has ISREG|ISBLK, this actually matches 6.0 semantics): any -> pipe via splice seekable -> any Also, there are many seekable files which aren't regular, and the offset is updated regardless. This is obvious, but the wording is clumsy. Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* unix.7: SO_PEERCRED: Mention listen(2)Alexey Tikhonov2023-12-21-1/+2
| | | | | | | | | | | | | | | | | | In case of connected AF_UNIX stream sockets, server-side credentials are set at the time of a call to listen(2), not when client-side calls connect(2). This is important if server side process changes UID/GID after listen(2) and before connect(2). Reproducer is available in [1]. Behavior was confirmed in the email thread [2]. Link: [1] <https://bugzilla.redhat.com/show_bug.cgi?id=2247682> Link: [2] <https://lore.kernel.org/linux-man/CABPeg3a9L0142gmdZZ+0hoD+Q3Vgv0BQ21g8Z+gf2kznWouErA@mail.gmail.com/> Signed-off-by: Alexey Tikhonov <atikhono@redhat.com> Reviewed-by: Kuniyuki Iwashima <kuniyu@amazon.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* strtol.3, strtoul.3: If the base is not supported, endptr may be left untouchedAlejandro Colomar2023-12-19-0/+6
| | | | Signed-off-by: Alejandro Colomar <alx@kernel.org>
* README: Versions: Document the online pages in man7.orgAlejandro Colomar2023-12-17-0/+2
| | | | | | Michael's online pages seem to be more-or-less up-to-date now. Signed-off-by: Alejandro Colomar <alx@kernel.org>
* string_copying.7: EXAMPLES: st[rp]ncpy(3): Use fwrite(3) instead of a loopAlejandro Colomar2023-12-17-4/+2
| | | | Signed-off-by: Alejandro Colomar <alx@kernel.org>
* string_copying.7: Use NITEMS() instead of sizeof()Alejandro Colomar2023-12-17-14/+14
| | | | | | | | | For these byte functions, sizeof() works as well as NITEMS(), since CHAR_BIT == 1. However, equivalent wide-character functions need NITEMS(), which is semantically more appropriate, and also safer (it cannot be applied to pointers). Signed-off-by: Alejandro Colomar <alx@kernel.org>
* string_copying.7: EXAMPLES: Update stpecpy() exampleAlejandro Colomar2023-12-17-2/+2
| | | | | | | The function was changed recently to return NULL on truncation; update the example of use accordingly. Signed-off-by: Alejandro Colomar <alx@kernel.org>
* string_copying.7: stpecpy(): Reimplement as a wrapper of strtcpy()Alejandro Colomar2023-12-17-16/+3
| | | | Signed-off-by: Alejandro Colomar <alx@kernel.org>
* string_copying.7: stpecpy(): Return NULL on truncationAlejandro Colomar2023-12-17-19/+19
| | | | | | | | | | This makes it simpler to test the return value, and since it sets errno to find out the reason, we don't need a complex return value. Now that (dst == end) shouldn't happen, use ENOBUFS to report that error. Signed-off-by: Alejandro Colomar <alx@kernel.org>
* string_copying.7: stpecpy(), strtcpy(): Set errno on failureAlejandro Colomar2023-12-17-4/+36
| | | | Signed-off-by: Alejandro Colomar <alx@kernel.org>
* swapon.2: Adjust decreased value under CONFIG_PTE_MARKERYang Xu2023-12-17-0/+4
| | | | | | | | | Since linux 5.19[1], MAX_SWAPFILES will be futher decreased 1 if kernel built with CONFIG_PTE_MARKER. Link: [1] <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/include/linux/swap.h?id=679d10331> Signed-off-by: Yang Xu <xuyang2018.jy@fujitsu.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* swapon.2: Adjust decreased value under CONFIG_MIGRATIONYang Xu2023-12-17-1/+2
| | | | | | | | Since Linux 5.19[1], the limit is decreased by 3 instead of 2. Link: [1] <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/include/linux/swap.h?id=6c287605f> Signed-off-by: Yang Xu <xuyang2018.jy@fujitsu.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* scanf.3: BUGS: It's impossible to know how many characters were consumedAlejandro Colomar2023-12-09-0/+9
| | | | | Suggested-by: Zack Weinberg <zack@owlfolio.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* scanf.3, sscanf.3: These functions scan formatted inputAlejandro Colomar2023-12-09-2/+2
| | | | | Suggested-by: Lee Griffiths <poddster@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* mbind.2: Add mode flag MPOL_F_NUMA_BALANCINGYafang Shao2023-12-09-0/+17
| | | | | | | | | | | | | | | | | | | | | In Linux Kernel 5.12, a new mode flag, MPOL_F_NUMA_BALANCING, was added to set_mempolicy() to optimize the page placement among the NUMA nodes with the NUMA balancing mechanism even if the memory of the applications is bound with MPOL_BIND. In Linux Kernel 5.15, this mode flag was extended to mbind(2). Let's also add man-page for mbind(2). It is copied from set_mempoicy(2) man-page with subtle modifications. Related kernel commits: bda420b985054a3badafef23807c4b4fa38a3dff 6d2aec9e123bb9c49cb5c7fc654f25f81e688e8c Suggested-by: "Huang, Ying" <ying.huang@intel.com> Signed-off-by: Yafang Shao <laoar.shao@gmail.com> Cc: "Huang, Ying" <ying.huang@intel.com> Cc: Michael Kerrisk <mtk.manpages@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* scanf.3: CAVEATS: Trailing text cannot be checkedAlejandro Colomar2023-12-09-0/+3
| | | | | | | | scanf("%d foo"); It is impossible to know if scanf(3) consumed " foo" or not. Signed-off-by: Alejandro Colomar <alx@kernel.org>
* scanf.3: CAVEATS: These functions don't distinguish newlines easilyAlejandro Colomar2023-12-09-0/+5
| | | | | | | One could use "%*1[\n]" for specifying a newline, and "%*[ \t] for other white space. Signed-off-by: Alejandro Colomar <alx@kernel.org>
* strtol.3: Clarify that the base should be tested beforehand, if at allAlejandro Colomar2023-12-06-3/+25
| | | | | | | | | | | | | | | | | | Normally, the base need not be tested, and the only interesting errno value should be ERANGE. If the base needs to be tested, it should be tested in a call that would not otherwise fail. Otherwise, it would be easy to trigger Undefined Behavior. Consider the following example: errno = 0; val = strtol("foo", &end, -42); There's no portable way to know if the call failed due to the string or the base. Cc: Matthew House <mattlloydhouse@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* sscanf.3: Remove term 'deprecated', and expand BUGSAlejandro Colomar2023-12-06-13/+2
| | | | | | | | | | | | | | | | | | | Several programmers have been confused about this use of 'deprecated'. Also, maximum field width can be used with these fields to mitigate the problem. Still, it's only a mitigation, since it limits the number of characters read, but that means an input of LONG_MAX+1 --which takes up the same number of characters than LONG_MAX-- would still cause UB; or one can limit that to well below the limit of UB, but then it artificially invalidates valid input. No good way to avoid UB with sscanf(3), but it's not necessarily bad with trusted input (and strtol(3) isn't the panacea either: it avoids UB, but error checking is hard; strtoi(3) is good, though, but not standard). Link: <https://stackoverflow.com/questions/77601832/man-sscanf-d-is-deprecated-in-c-or-glibc/> Cc: Lee Griffiths <poddster@gmail.com> Cc: Zack Weinberg <zack@owlfolio.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* string_copying.7: wfixAlejandro Colomar2023-12-05-1/+3
| | | | Signed-off-by: Alejandro Colomar <alx@kernel.org>
* string_copying.7: Generalize null-padded character sequences with strnlen(3)Alejandro Colomar2023-12-05-12/+7
| | | | Signed-off-by: Alejandro Colomar <alx@kernel.org>
* strncat.3: Clarify that it terminates the stringAlejandro Colomar2023-12-05-1/+2
| | | | Signed-off-by: Alejandro Colomar <alx@kernel.org>
* string_copying.7: Be consistent in the use of null byte and null characterAlejandro Colomar2023-12-04-12/+13
| | | | | | | Null character, for the terminating character of a string. Null byte, for the padding. Signed-off-by: Alejandro Colomar <alx@kernel.org>
* string_copying.7: Don't say 'size' when 'len' is meantAlejandro Colomar2023-12-04-6/+6
| | | | Signed-off-by: Alejandro Colomar <alx@kernel.org>
* string_copying.7: Say 'known-length' for character sequences whose length is ↵Alejandro Colomar2023-12-04-10/+10
| | | | | | known Signed-off-by: Alejandro Colomar <alx@kernel.org>
* string_copying.7: Don't say 'width' when 'size' is meantAlejandro Colomar2023-12-04-9/+9
| | | | | Reported-by: Paul Eggert <eggert@cs.ucla.edu> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* string_copying.7: RETURN VALUE: Remove some confusing text about stpncpy(3)Alejandro Colomar2023-12-04-7/+2
| | | | | | | That text could lead someone to think that it's possible to check truncation from the return value, but it isn't. Signed-off-by: Alejandro Colomar <alx@kernel.org>
* string_copying.7: Consistently list strtcpy() after stpecpy()Alejandro Colomar2023-12-04-43/+43
| | | | | | And put it next to strlcpy(3bsd), which is very similar to strtcpy(). Signed-off-by: Alejandro Colomar <alx@kernel.org>
* string_copying.7: stpecpy() and strtcpy() don't exist in man3Alejandro Colomar2023-12-04-19/+19
| | | | Signed-off-by: Alejandro Colomar <alx@kernel.org>
* string_copying.7: Use fwrite(3) to print character sequencesAlejandro Colomar2023-12-04-2/+2
| | | | | Suggested-by: Paul Eggert <eggert@cs.ucla.edu> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* string_copying.7: tfixAlejandro Colomar2023-12-04-1/+1
| | | | Signed-off-by: Alejandro Colomar <alx@kernel.org>
* string_copying.7: Use real examples with utmp(5)Alejandro Colomar2023-12-04-22/+16
| | | | | | | | | For the functions that are designed to be used with utmp(5) or similar APIs, use utmp(5) in the example, which results in a clearer example, and also more realistic. It better clarifies how these functions are to be used. Signed-off-by: Alejandro Colomar <alx@kernel.org>
* strncat.3: Fix return value of possible implementationAlejandro Colomar2023-12-04-1/+2
| | | | | | | Accidentally, I changed the return while changing something else. Fix it. Fixes: 790795ec4e5e ("strncat.3: Write the null byte with stpcpy(3)") Signed-off-by: Alejandro Colomar <alx@kernel.org>
* string_copying.7: Improve strncat(3) exampleAlejandro Colomar2023-12-04-4/+5
| | | | Signed-off-by: Alejandro Colomar <alx@kernel.org>
* string_copying.7: Reimplement stpecpy()Alejandro Colomar2023-12-04-8/+9
| | | | | | | | This implementation resembles more strtcpy(), so the differences are more visible. Also, it has no -1's, so it's a bit easier to implement correctly. Signed-off-by: Alejandro Colomar <alx@kernel.org>
* strncat.3: Write the null byte with stpcpy(3)Alejandro Colomar2023-12-04-5/+1
| | | | Signed-off-by: Alejandro Colomar <alx@kernel.org>
* strncat.3: Implement strncat(3) in terms of strnul()Alejandro Colomar2023-12-04-1/+2
| | | | Signed-off-by: Alejandro Colomar <alx@kernel.org>
generated by cgit v1.2.3 (git 2.39.1) at 2024-05-17 11:04:53 +0000