Tuesday, November 19, 2019

man-pages-5.04 is released

I've released man-pages-5.04. The release tarball is available on kernel.org. The browsable online pages can be found on man7.org. The Git repository for man-pages is available on kernel.org.

This release resulted from patches, bug reports, reviews, and comments from 15 contributors. The release includes approximately 80 commits that change just under 30 pages.

The most notable of the changes in man-pages-5.04 are the following:

  • With some help from Christian Brauner, I've added documentation of the clone3() system call (new in Linux 5.3) to the clone(2) manual page. In addition, several other parts of the clone(2) manual page were cleaned up and reworked.
  • I've refreshed the the bpf-helpers(7) page against the latest kernel sources; as a result, the page has grown size by about 25%.
Another small but important change is the addition of documentation of the P_PIDFD idtype in the waitid(2) manual page. This feature, added in Linux 5.4, allows a parent process to wait on a child process that is referred to by a PID file descriptor, and constitutes the final cornerstone in the pidfd API.

Friday, October 11, 2019

man-pages-5.03 is released

I've released man-pages-5.03. The release tarball is available on kernel.org. The browsable online pages can be found on man7.org. The Git repository for man-pages is available on kernel.org.

This release resulted from patches, bug reports, reviews, and comments from 45 contributors. The release includes over 200 commits that change around 80 pages.

The most notable of the changes in man-pages-5.03 are the following:

  • I've written a new pidfd_send_signal(2) page that documents the system call  of the same name. This system call, which was added in Linux 5.1, makes it possible to send a signal to a process referred to via a file descriptor. This allows the avoidance of race conditions that can occur using traditional APIs (e.g., kill(2)) to signal a process, which may result in signaling the wrong process if the intended target process has already terminated and its PID has been recycled.
  • I've written a new pidfd_open(2) page that documents the system call  of the same name. This system call, which was added in Linux 5.3, can be used to obtain a file descriptor for a process with a specified PID. This file descriptor can be used as argument to pidfd_send_signal(). Soon (Linux 5.4), it will also be  possible to use this file descriptor to wait for the process using waitid(2).
  • I've completely rewritten the pivot_root(2) manual page, adding a lot of missing details (including the use of pivot_root(".", ".")) and an example program.  In addition, the text prevaricating on whether or not pivot_root() might change the root and current working directories has been eliminated, and replaced with a simple description of the behavior of the system call, which has not changed for 19 years, and will not change in the future.  Many longstanding errors in the old version of the page have also been corrected.
  • Christian Brauner added documentation of the CLONE_PIDFD flag to the clone(2) manual page.  This flag (added in Linux 5.2) can be used to obtain a file descriptor that refers to the child process created by clone(2). This file descriptor can be used for the same purposes as the file descriptor returned by pidfd_open(2).
  • Dmitry Levin as added documentation of a new option, PTRACE_GET_SYSCALL_INFO, to the ptrace(2) manual page.
  • Two new pages, ipc_namespaces(7) and uts_namespaces(7), have been created by splitting out content that was formerly part of the namespaces(7) page.

Friday, August 2, 2019

man-pages-5.02 is released

I've released man-pages-5.02. The release tarball is available on kernel.org. The browsable online pages can be found on man7.org. The Git repository for man-pages is available on kernel.org.

This release resulted from patches, bug reports, reviews, and comments from 28 contributors. The release includes around 120 commits that change more than 50 pages.

The most notable of the changes in man-pages-5.02 is the following:

  • Thanks to Matthew Bobrowski, extensive documentation of FAN_REPORT_FID and directory modification events has been added to the fanotify(7), fanotify_init(2), and fanotify_mark(2) pages.
  • I have added several details on the dlopen API to the dlopen(3) page.
  • I've corrected a few longstanding errors and omissions in the pivot_root(2) manual page, and much more extensive changes for this page are in the pipeline for the next release.

Thursday, May 9, 2019

man-pages-5.01 is released

I've released man-pages-5.01. The release tarball is available on kernel.org. The browsable online pages can be found on man7.org. The Git repository for man-pages is available on kernel.org.

This release resulted from patches, bug reports, reviews, and comments from just over 20 contributors. The release is smaller release than typical; it includes just over 70 commits that changed just over 40 pages.

The most notable of the changes in man-pages-5.01 is the following:

  • The tsearch(3) page adds documentation of the new twalk_r() function that is added in the upcoming glibc 2.30 release. Thanks to Florian Weimer.

Wednesday, March 6, 2019

man-pages-5.00 is released

I've released man-pages-5.00. The release tarball is available on kernel.org. The browsable online pages can be found on man7.org. The Git repository for man-pages is available on kernel.org.

This release resulted from patches, bug reports, reviews, and comments from around 130 contributors. The release is rather larger than average, since it has been nearly a year since the last release. The release includes more than 600 commits that changed nearly 400 pages. In addition, 3 new manual pages were added.

Among the more significant changes in man-pages-5.,00 are the following:

  • A new page, bpf-helpers(7), documents the helper functions that the kernel provide for eBPF programs to call. This page is autogenerated from kernel files, and was brought to life in the man-pages project by Quentin Monnet.
  • Various updates to the perf_event_open(2) page by Vince Weaver.
  • A new s390_guarded_storage(2) page by Eugene Syromyatnikov documents the s390-specific system call of the same name.
  • The addition of many formerly absent architecture-specific system calls in the table of system calls shown syscalls(2).
  • A significant overhaul of the lirc4) page by Sean Young.
  • Many additions to the proc(5) page.
  • Much of the detail on socket address families in the rather overloaded socket(2) page has now been moved to a new address_families(7) page.
  • A large number of additions, mostly by me, in the capabilities(7) page.
  • Many improvements, all by me, in the discussion of ancillary data in the unix(7) page.
In addition, two pages have been removed in this release after encouragement from Ingo Schwarze: mdoc(7) and mdoc.samples(7). As the commit message notes, groff_mdoc(7) from the groff project provides a better equivalent of mdoc.samples(7) and the mandoc project provides a better mdoc(7). And nowadays, there are virtually no pages in man-pages that use mdoc markup.

Again special thanks to Eugene Syromyatnikov, who contributed nearly 30 patches to this release!