| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <20241101132437.ahn7xdgvmqamatce@devuan>
Date: Fri, 1 Nov 2024 14:24:37 +0100
From: Alejandro Colomar <alx@...nel.org>
To: Ian Rogers <irogers@...gle.com>
Cc: "G . Branden Robinson" <g.branden.robinson@...il.com>,
David Airlie <airlied@...il.com>, Simona Vetter <simona@...ll.ch>,
Maarten Lankhorst <maarten.lankhorst@...ux.intel.com>,
Maxime Ripard <mripard@...nel.org>,
Thomas Zimmermann <tzimmermann@...e.de>,
Jonathan Corbet <corbet@....net>, dri-devel@...ts.freedesktop.org,
linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
linux-man@...r.kernel.org
Subject: Re: [PATCH v2 1/3] proc_pid_fdinfo.5: Reduce indent for most of the
page
On Tue, Oct 15, 2024 at 02:17:17PM -0700, Ian Rogers wrote:
> When /proc/pid/fdinfo was part of proc.5 man page the indentation made
> sense. As a standalone man page the indentation doesn't need to be so
> far over to the right. Remove the initial tagged pragraph and move the
> styling to the initial summary description.
>
> Suggested-by: G. Branden Robinson <g.branden.robinson@...il.com>
> Signed-off-by: Ian Rogers <irogers@...gle.com>
> ---
> man/man5/proc_pid_fdinfo.5 | 66 ++++++++++++++++++--------------------
> 1 file changed, 32 insertions(+), 34 deletions(-)
>
> diff --git a/man/man5/proc_pid_fdinfo.5 b/man/man5/proc_pid_fdinfo.5
> index 1e23bbe02..8678caf4a 100644
> --- a/man/man5/proc_pid_fdinfo.5
> +++ b/man/man5/proc_pid_fdinfo.5
> @@ -6,20 +6,19 @@
> .\"
> .TH proc_pid_fdinfo 5 (date) "Linux man-pages (unreleased)"
> .SH NAME
> -/proc/pid/fdinfo/ \- information about file descriptors
> +.IR /proc/ pid /fdinfo " \- information about file descriptors"
I wouldn't add formatting here for now. That's something I prefer to be
cautious about, and if we do it, we should do it in a separate commit.
> .SH DESCRIPTION
> -.TP
> -.IR /proc/ pid /fdinfo/ " (since Linux 2.6.22)"
> -This is a subdirectory containing one entry for each file which the
> -process has open, named by its file descriptor.
> -The files in this directory are readable only by the owner of the process.
> -The contents of each file can be read to obtain information
> -about the corresponding file descriptor.
> -The content depends on the type of file referred to by the
> -corresponding file descriptor.
> -.IP
> +Since Linux 2.6.22,
You could move this information to a HISTORY section.
> +this subdirectory contains one entry for each file that process
> +.I pid
> +has open, named by its file descriptor. The files in this directory
Please don't reflow existing text. Please read about semantic newlines
in man-pages(7):
$ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
Use semantic newlines
In the source of a manual page, new sentences should be started
on new lines, long sentences should be split into lines at clause
breaks (commas, semicolons, colons, and so on), and long clauses
should be split at phrase boundaries. This convention, sometimes
known as "semantic newlines", makes it easier to see the effect
of patches, which often operate at the level of individual sen‐
tences, clauses, or phrases.
Have a lovely day!
Alex
> +are readable only by the owner of the process. The contents of each
> +file can be read to obtain information about the corresponding file
> +descriptor. The content depends on the type of file referred to by
> +the corresponding file descriptor.
> +.P
> For regular files and directories, we see something like:
> -.IP
> +.P
> .in +4n
> .EX
> .RB "$" " cat /proc/12015/fdinfo/4"
> @@ -28,7 +27,7 @@ flags: 01002002
> mnt_id: 21
> .EE
> .in
> -.IP
> +.P
> The fields are as follows:
> .RS
> .TP
> @@ -51,7 +50,6 @@ this field incorrectly displayed the setting of
> at the time the file was opened,
> rather than the current setting of the close-on-exec flag.
> .TP
> -.I
> .I mnt_id
> This field, present since Linux 3.15,
> .\" commit 49d063cb353265c3af701bab215ac438ca7df36d
> @@ -59,13 +57,13 @@ is the ID of the mount containing this file.
> See the description of
> .IR /proc/ pid /mountinfo .
> .RE
> -.IP
> +.P
> For eventfd file descriptors (see
> .BR eventfd (2)),
> we see (since Linux 3.8)
> .\" commit cbac5542d48127b546a23d816380a7926eee1c25
> the following fields:
> -.IP
> +.P
> .in +4n
> .EX
> pos: 0
> @@ -74,16 +72,16 @@ mnt_id: 10
> eventfd\-count: 40
> .EE
> .in
> -.IP
> +.P
> .I eventfd\-count
> is the current value of the eventfd counter, in hexadecimal.
> -.IP
> +.P
> For epoll file descriptors (see
> .BR epoll (7)),
> we see (since Linux 3.8)
> .\" commit 138d22b58696c506799f8de759804083ff9effae
> the following fields:
> -.IP
> +.P
> .in +4n
> .EX
> pos: 0
> @@ -93,7 +91,7 @@ tfd: 9 events: 19 data: 74253d2500000009
> tfd: 7 events: 19 data: 74253d2500000007
> .EE
> .in
> -.IP
> +.P
> Each of the lines beginning
> .I tfd
> describes one of the file descriptors being monitored via
> @@ -110,13 +108,13 @@ descriptor.
> The
> .I data
> field is the data value associated with this file descriptor.
> -.IP
> +.P
> For signalfd file descriptors (see
> .BR signalfd (2)),
> we see (since Linux 3.8)
> .\" commit 138d22b58696c506799f8de759804083ff9effae
> the following fields:
> -.IP
> +.P
> .in +4n
> .EX
> pos: 0
> @@ -125,7 +123,7 @@ mnt_id: 10
> sigmask: 0000000000000006
> .EE
> .in
> -.IP
> +.P
> .I sigmask
> is the hexadecimal mask of signals that are accepted via this
> signalfd file descriptor.
> @@ -135,12 +133,12 @@ and
> .BR SIGQUIT ;
> see
> .BR signal (7).)
> -.IP
> +.P
> For inotify file descriptors (see
> .BR inotify (7)),
> we see (since Linux 3.8)
> the following fields:
> -.IP
> +.P
> .in +4n
> .EX
> pos: 0
> @@ -150,7 +148,7 @@ inotify wd:2 ino:7ef82a sdev:800001 mask:800afff ignored_mask:0 fhandle\-bytes:8
> inotify wd:1 ino:192627 sdev:800001 mask:800afff ignored_mask:0 fhandle\-bytes:8 fhandle\-type:1 f_handle:27261900802dfd73
> .EE
> .in
> -.IP
> +.P
> Each of the lines beginning with "inotify" displays information about
> one file or directory that is being monitored.
> The fields in this line are as follows:
> @@ -168,19 +166,19 @@ The ID of the device where the target file resides (in hexadecimal).
> .I mask
> The mask of events being monitored for the target file (in hexadecimal).
> .RE
> -.IP
> +.P
> If the kernel was built with exportfs support, the path to the target
> file is exposed as a file handle, via three hexadecimal fields:
> .IR fhandle\-bytes ,
> .IR fhandle\-type ,
> and
> .IR f_handle .
> -.IP
> +.P
> For fanotify file descriptors (see
> .BR fanotify (7)),
> we see (since Linux 3.8)
> the following fields:
> -.IP
> +.P
> .in +4n
> .EX
> pos: 0
> @@ -190,7 +188,7 @@ fanotify flags:0 event\-flags:88002
> fanotify ino:19264f sdev:800001 mflags:0 mask:1 ignored_mask:0 fhandle\-bytes:8 fhandle\-type:1 f_handle:4f261900a82dfd73
> .EE
> .in
> -.IP
> +.P
> The fourth line displays information defined when the fanotify group
> was created via
> .BR fanotify_init (2):
> @@ -210,7 +208,7 @@ argument given to
> .BR fanotify_init (2)
> (expressed in hexadecimal).
> .RE
> -.IP
> +.P
> Each additional line shown in the file contains information
> about one of the marks in the fanotify group.
> Most of these fields are as for inotify, except:
> @@ -228,16 +226,16 @@ The events mask for this mark
> The mask of events that are ignored for this mark
> (expressed in hexadecimal).
> .RE
> -.IP
> +.P
> For details on these fields, see
> .BR fanotify_mark (2).
> -.IP
> +.P
> For timerfd file descriptors (see
> .BR timerfd (2)),
> we see (since Linux 3.17)
> .\" commit af9c4957cf212ad9cf0bee34c95cb11de5426e85
> the following fields:
> -.IP
> +.P
> .in +4n
> .EX
> pos: 0
> --
> 2.47.0.rc1.288.g06298d1525-goog
>
--
<https://www.alejandro-colomar.es/>
Download attachment "signature.asc" of type "application/pgp-signature" (834 bytes)
Powered by blists - more mailing lists