The section "Example Programs ..." was renamed to "Example programs ..."
(with lowercase p) in c634028ab5, but the reference was not
updated.
Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
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.
So, drop these pages.
From a conversation on linux-man with Ingo Schwarz:
[[
Subject: Re: [groff] [PATCH] man7/mdoc_samples.7: srcfix: Avoid a warning about a wrong section
Date: Wed, 27 Feb 2019 15:28:19 +0100
> The two actual problems are both within the Linux man-pages project,
> not within groff:
>
> 1. While back in the early 1990ies, Cynthia Livingston's
> mdoc.samples(7) manual page was an important document and the
> de-facto language definition of the mdoc(7) language, it has
> been outdated for a long time now. The current groff_mdoc(7)
> manual page is based on it but contains large numbers of important
> improvements by Werner Lemberg and others. As an alternative
> language definition that is slightly more concise without being
> less precise and complete, the mdoc(7) manual page is available
> from the mandoc(1) distribution (mandoc.bsd.lv). If there are
> any contradictions between groff_mdoc(7) and mdoc(7), those are
> unintended and i ought to fix them.
>
> So i really believe that the Linux man-pages project ought to
> stop distributing the woefully outdated mdoc.samples(7) manual
> page. If you want to include documentation for the mdoc language,
> i suggest that you either include a copy of the current version
> of the groff_mdoc(7) manual from the groff(1) distribution or
> of the mdoc(7) manual from the mandoc(1) distribution, whichever
> you think harmonizes better with the Linux man-pages project.
> Both are BSD-style licensed, so there should be no licensing
> issues.
>
> I'm not sure whether it is better for you to include or not
> include it. There is probably value in having mdoc(7) documentation
> out of the box with the Linux man-pages project. Then again,
> having groff_mdoc(7) in both the Linux man-pages package and
> in the groff package - or having mdoc(7) in both the Linux
> man-pages project and the mandoc(1) package - might cause
> packaging conflicts for some distributions. I don't rightly
> know how such conflicts are typically handled by Linux
> distributions. Not being able to install the Linux man-pages
> pages project, groff(1) and mandoc(1) all together on the same
> Linux machine would certainly be a bad situation...
>
> By the way, the mdoc(7) manual page distributed by the Linux
> man-pages project also makes very little sense. It is a partial
> repetition of information from groff_mdoc(7)/[mandoc-]mdoc(7),
> but so compressed that it is mostly unintelligible. Besides,
> it is incomplete: e.g. .Lk, .Mt, .Dx, .Ox, .Nx, .Ta, .%U, .Bk,
> .Ek, .Lb, .In, .Ft, .Ms, .Brq, .Bro, .Brc, .Ex are missing -
> it seems outdated by at lest 25 years. Also, some claims are
> outright wrong - for example, you *cannot* use .UR/.UE in an
> mdoc(7) document, and i cannot remember ever having seen an
> implementation of a .UN macro anywhere. Some macros descriptions
> are also wrong, e.g. .Fd is *not* intended for "function
> declarations", and .Vt is *not* "Fortran only". And so on.
>
> 2. I don't recommend keeping the old mdoc.samples(7) and mdoc(7)
> manual pages, but if you think you must do that for some reason,
> then you must at least revert this bogus commit:
I am *not at all* attached to keeping to these pages. Their
presence in the project has always felt a bit anomalous to me.
Back when I took over maintainership in 2004, there were a small
number of pages that used mdoc markup, and so it seemed wise
to keep these pages. Over time, most of those few pages were
converted to 'man' markup, and today the only other page in the
project that still uses mdoc markup is in queue(3). So, there is
just about zero value in having 'mdoc' documentation come with
the "Linux man-pages" box.
Since I seldom use mdoc markup myself, I've had no reason to
monitor pages such as groff_mdoc(7) or the mdoc(7) page
provided my ther 'mandoc' project and compare them with
the pages provided by "Linux man-pages". Now I've had a
closer look. It's sad.
I've removed mdoc(7) and mdoc.samples(7) from "Linux -man-pages".
]]
Reported-by: Ingo Schwarze <schwarze@usta.de>
Quoting Branden:
*roff escape sequences may sometimes look like C escapes, but that
is misleading. *roff is in part a macro language and that means
recursive expansion to arbitrary depths.
You can get away with "\\" in a context where no macro expansion
is taking place, but try to spell a literal backslash this way in
the argument to a macro and you will likely be unhappy with
results.
Try viewing the attached file with "man -l".
"\e" is the preferred and portable way to get a portable "escape
literal" going back to CSTR #54, the original Bell Labs troff
paper.
groff(7) discusses the issue:
\\ reduces to a single backslash; useful to delay its
interpretation as escape character in copy mode. For a
printable backslash, use \e, or even better \[rs], to be
independent from the current escape character.
As of groff 1.22.4, groff_man(7) does as well:
\e Widely used in man pages to represent a backslash output
glyph. It works reliably as long as the .ec request is
not used, which should never happen in man pages, and it
is slightly more portable than the more exact ‘\(rs’
(“reverse solidus”) escape sequence.
People not concerned with portability to extremely old troffs should
probably just use \(rs (or \[rs]), as it means "the backslash
glyph", not "the glyph corresponding to whatever the current escape
character is".
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Quoting Branden:
*roff systems will interpret the period in the unpatched
page as sentence-ending punctuation and put inter-sentence
spacing after it. (This might not be visible on
nroff/terminal devices, but it is more likely to be on
typesetter/PostScript/PDF output).
groff_man(7) in groff 1.22.4 attempts to throw man page
writers a bone here:
\& Zero‐width space. Append to an input line to prevent
an end‐of‐ sentence punctuation sequence from being
recognized as such, or insert at the beginning of an
input line to prevent a dot or apostrophe from being
interpreted as the beginning of a roff request.
Reported-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
Reported-by: G. Branden Robinson <g.branden.robinson@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
fanotify_init.2: add new flag FAN_REPORT_TID
fanotify.7: update description of member pid in
struct fanotify_event_metadata
Signed-off-by: nixiaoming <nixiaoming@huawei.com>
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Monitor fanotify events on the entire filesystem.
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
New event masks have been added to the fanotify API. Documentation to
support the use and behaviour of these new masks has been added
accordingly.
Signed-off-by: Matthew Bobrowski <mbobrowski@mbobrowski.org>
Reviewed-by: Amir Goldstein <amir73il@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Add documentation for new flag IN_MASK_CREATE for inotify_add_watch()
which is used to only allow new watches to be created.
Information obtained from a patch I submitted to the linux kernel
https://marc.info/?l=linux-fsdevel&m=152775980422847&w=2
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
* man2/socket.2 (.SH DESCRIPTION): Mention that the list of
address families is Linux-specific.
* man7/address_families.7 (.SH DESCRIPTION): Likewise.
Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
I need to get the TTL of UDP datagrams from userspace, so I set
the IP_RECVTTL socket option. And as promised by ip.7, I then get
IP_TTL messages from recvfrom. However, unlike what the manpage
promises, the TTL field gets passed as a 32 bit integer.
The following userspace code works:
uint32_t ttl32;
for (cmsg = CMSG_FIRSTHDR(msgh); cmsg != NULL; cmsg = CMSG_NXTHDR(msgh,cmsg)) {
if ((cmsg->cmsg_level == IPPROTO_IP) && (cmsg->cmsg_type == IP_TTL) &&
CMSG_LEN(sizeof(ttl32)) == cmsg->cmsg_len) {
memcpy(&ttl32, CMSG_DATA(cmsg), sizeof(ttl32));
*ttl=ttl32;
return true;
}
else
cerr<<"Saw something else "<<(cmsg->cmsg_type == IP_TTL) <<
", "<<(int)cmsg->cmsg_level<<", "<<cmsg->cmsg_len<<", "<<
CMSG_LEN(1)<<endl;
}
The 'else' field was used to figure out I go the length wrong.
Note from mtk:
Reading the source code also seems to confirm this, from
net/ipv4/ip_sockglue.c:
[[
static void ip_cmsg_recv_ttl(struct msghdr *msg, struct sk_buff *skb)
{
int ttl = ip_hdr(skb)->ttl;
put_cmsg(msg, SOL_IP, IP_TTL, sizeof(int), &ttl);
}
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This best belongs at the end of the page, after the subsections
that already make some mention of user namespaces.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The text stated that the execve() capability transitions are not
performed for the same reasons that setuid and setgid mode bits
may be ignored (as described in execve(2)). But, that's not quite
correct: rather, the file capability sets are treated as empty
for the purpose of the capability transition calculations.
Also merge the new 'no_file_caps' kernel option text into the
same paragraph.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Clarify the "Capabilities and execution of programs by root"
section, and correct a couple of details:
* If a process with rUID == 0 && eUID != 0 does an exec,
the process will nevertheless gain effective capabilities
if the file effective bit is set.
* Set-UID-root programs only confer a full set of capabilities
if the binary does not also have attached capabilities.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk