Friday, August 27, 2021

man-pages-5.13 released

Alex Colomar and I have released released man-pages-5.13. 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 40 contributors. The release includes around 200 commits that changed around 120 manual pages.

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

  • A new mount_setattr(2) page, written by Christian Brauner, that documents the mount_setattr() system call added in Linux 5.12.
  • I added documentation of the /proc/PID/projid_map file to the user_namespaces(7) page.
  • I added a greatly expanded description of the concept of locked mounts in the mount_namespaces(7) page.

Special thanks again to Alex, who kept track of a lot of patches while I was unavailable.

Tuesday, June 22, 2021

man-pages-5.12 released

Alex Colomar and I have released released man-pages-5.12. 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 40 contributors. The release includes more than 300 commits that changed around 180 manual pages.

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

  • A very large number of global edits by Alex Colomar to the SYNOPSIS section of many manual pages. These include changes to the way the system calls that have no wrapper function in glibc are documented, as well more precise information about which header files are needed, and why, by various APIs.
  • A new seccomp_unotify(2) page, written by me (with help from Tycho Andersen, Jann Horn, Kees Cook, Christian Brauner, and Sargun Dhillon), that documents the seccomp user-space notification feature.
  • Alex Colomar wrote a new MAX(3) manual page documenting the MAX() and MIN() functions provided by glibc.
  • Alex Colomar added a documentation of a number of further types to the system_data_types(7) page.

Special thanks to Alex, who was once again the largest contributor in this release!

Monday, March 22, 2021

man-pages-5.11 is released

Alex Colomar and I have released released man-pages-5.11. 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 40 contributors. A number of wide-ranging global edits by Alex and me have resulted in one of the largest releases since I became involved with man-pages some 20 years ago. The release includes around 480 commits that changed around 950 (more than 90% of the) manual pages. The diff runs to more than 50k lines (which makes it the third largest release measured by lines changed).

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

  • A new close_range(2) page, written by Stephen Kitt and me, documents the close_range() system call that was added in Linux 5.9.
  • A new process_madvise(2) page, written by Suren Baghdasaryan and Minchan Kim, documents the process_madvise() system call that was added in Linux 5.10.
  • Alex Colomar made a long overdue global fix to the manual pages, adding the restrict keyword to function signatures in the SYNOPSIS of all manual pages that required it. This resulted in changes to around 135 pages!
  • Alex Colomar removed the <sys/types.h> header file from the SYNOPSIS of many pages where that header is no longer required. (The standard removed such requirements 20+ years ago.)
  • Willem de Bruijn added documentation of the epoll_pwait2() system call (new in Linux 5.11) to the epoll_wait(2) page.
  • Gabriel Krisman Bertazi added documentation of the Syscall User Dispatch mechanism to the prctl(2) page.
  • I added documentation of the mallinfo2() function (new in glibc 2.33) to the mallinfo(3) page.
  • I have made global edits to improve consistency and layout in the SYNOPSIS (feature test macros), RETURN VALUE, and ATTRIBUTES in a large number of pages. A summary of many of these changes has been captured in the new FORMATTING AND WORDING CONVENTIONS section in man-pages(7).
  • A new fileno(3) manual page  has been created by extracting content formerly in the ferror(3) page. This change reflects the fact that ferror() is in various ways different from the other functions documented in ferror(3).

Tuesday, December 22, 2020

man-pages-5.10 is released

Starting with this release, Alejandro (Alex) Colomar has joined me as project comaintainer, and we've released man-pages-5.10. 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 25 contributors. The release includes just over 150 commits that changed around 140 pages.

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

  • I've added documentation of the faccessat2() system call (new in Linux 5.10) to the access(2) manual page.
  •  I've added a new subsection to the signal(7) manual page that provides a "big picture" of what happens when a signal handler is executed.

Sunday, November 1, 2020

man-pages-5.09 is released

I've released man-pages-5.09. 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 more than 40 contributors. The release includes more than 500 commits that changed nearly 600 pages. Nine new pages were added in this release.

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

  • Alejandro Colomar created a very useful new page, system_data_types(7), which has summary information about many commonly used system data types (currently about 45 types). In addition, the pages has links for each type, so that now it is possible to type a command such as man timespec to to get information about that type, the header files that define it, and the primary APIs that use the type.
  • Alejandro also did a lot of work to split the former queue(3) page, which was a rather unwieldy description of dozen of APIs, into a number of smaller pages, each of which describes a subset of related APIs. The new pages are circleq(3), list(3), slist(3), stailq(3), and tailq(3). The now rather smaller queue(3) page, which has essentially become a summary of the APIs, has migrated to become queue(7).
  • In addition, Alejandro made a large number of consistency fixes across many pages, especially in the code examples, where many pieces of C code were made more correct.
  • I added a new pthread_attr_setsigmask_np(3) page, documenting the pthread_attr_setsigmask_np(3) and pthread_attr_getsigmask_np(3) functions that were added in glibc 2.32.
  • A new kernel_lockdown(7) page, written by David Howells with improvements from Heinrich Schuchardt, describes the Kernel Lockdown feature that was merged in Linux 5.4.
  • I added descriptions of the sigabbrev_np() and sigdescr_np() functions (new in glibc 2.32) to the strsignal(3) page.
  • I added descriptions of the strerrorname_np() and strerrordesc_np() functions (also new in glibc 2.32) to the strerror(3) manual page.
As is probably clear, Alejandro Colomar owns this release. With 265 commits, he was by some margin the top contributor, and I'm very happy to report that he beat me into second place as a contributor to this release (something that happened only once before since I became maintainer).

Thursday, August 13, 2020

man-pages-5.08 is released

I've released man-pages-5.08. 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 more than 30 contributors. The release includes more than 190 commits that change around 340 pages.

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

  • Dave Martin added documentation of some arm64-specific prctl() operations to the prctl(2) manual page.
  • Aleksa Sarai added some documentation of magic links to the symlink(7) page.
  • I've added documentation on the use of PID file descriptors with setns() to the setns(2) page.
  • I've made various typographical fixes to many manual pages so that certain characters render better on the terminal or in PDF-format, or both.

Tuesday, June 9, 2020

man-pages-5.07 is released

I've released man-pages-5.07. 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 more than 80 contributors. The release includes more than 380 commits that change more than 380 pages. One new page was added in this release, and one page was removed.

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

  • A new ioctl_fslabel(2) page, written by Eric Sandeen, adds documentation of ioctl() operations for getting and setting filesystem labels.
  • The ioctl_list(2) page has been removed. This page was first added more than 20 years ago, and provided a minimal amount of information about the ioctl() operations available at that time. Since that time it has seen hardly any updates, and is by now very much out of date. The fact that I received few complaints about the page is indicative that no-one really cares about its contents, and it seems appropriate to remove it.
  • The adjtimex(2) page adds documentation of the clock_adjtime() system call; thanks to Arnd Bergmann.
  • Many updates to the fanotify manual pages, thanks to Amir Goldstein.

Sunday, April 12, 2020

man-pages-5.06 is released

I've released man-pages-5.06. 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 39 contributors. The release includes more than 250 commits that change more than 120 pages. Three new pages were added in this release.

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

  • A new openat2(2) manual page, written by Aleksa Sarai, documents the system call of the same name that was added in Linux 5.6.
  • A new pidfd_getfd(2) page, written by me, documents the system call of the same name that was added in Linux 5.6.
  • A new time_namespaces(7) page, written by me, documents time namespaces, which were added in Linux 5.6.
  • Many details were added and improved in the clock_getres(2) page.
  • I have substantially revised the select(2) and select_tut(2)In the process, much information that was duplicated across both pages has been consolidated into the select(2) page. Existing text in select(2) was also substantially rewritten and restructured.
  • I have revised and trimmed the sysvipc(7) to be just a summary of the System V IPC APIs. Various details that formerly were in this page have been moved to relevant pages in section 2.
  • I've added example programs to several pages: clock_getres(2), poll(2), semget(2), shmop(2), shm_open(3), and strcmp(3).

Sunday, February 9, 2020

man-pages-5.05 is released

I've released man-pages-5.05. 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 more than 40 contributors. The release includes approximately 110 commits that change around 50 pages.

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!

Monday, April 30, 2018

man-pages-4.16 is released

I've released man-pages-4.16. 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 29 contributors. Somewhat more than 160 commits changed around 60 pages. A summary of the changes can be found here.