A naked tilde ("~") renders poorly in PDF. Instead use "\(ti",
which renders better in a PDF, and produces the same glyph
when rendering on a terminal.
Reported-by: Geoff Clare <gwc@opengroup.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Remove superfluous paragraph macros.
Remove ".br" if it is before a line that starts with a space
character, as such lines automatically cause a break.
###
The output is unchanged, except two empty lines are added at the
bottom (before the footer line) in the output of "nroff" for the files
"alloc_hugepages.2" and "userfaultfd.2".
###
Examples of warnings from "mandoc -Tlint":
mandoc: access.2:283:2: WARNING: skipping paragraph macro: PP after SH
mandoc: adjtimex.2:185:2: WARNING: skipping paragraph macro: PP empty
mandoc: futex.2:728:2: WARNING: skipping paragraph macro: IP empty
mandoc: getsid.2:48:2: WARNING: skipping paragraph macro: br before text line with leading blank
mandoc: init_module.2:290:2: WARNING: skipping paragraph macro: PP after SS
mandoc: ioctl_fideduperange.2:27:2: WARNING: skipping paragraph macro: br after SH
Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In the few pages where this heading (which is "nonstandard" within
man-pages) is used, it always immediately follows CONFORMING TO
and generally contains information related to standards. Remove
the section heading, thus incorporating AVAILABILITY into
CONFORMING TO.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
EXAMPLES appears to be the wider majority usage across various
projects' manual pages, and is also what is used in the POSIX
manual pages.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
From a mailing list conversation:
On 5/24/18 9:03 PM, Heinrich Schuchardt wrote:
> Hello Michael,
>
> in the mmap(2) man page MAP_ANON is described as deprecated.
>
> When I look at the NetBSD manpage
> http://netbsd.gw.com/cgi-bin/man-cgi?mmap+2+NetBSD-current
> I found that MAP_ANONYMOUS is not defined.
>
> https://www.dragonflybsd.org/cgi/web-man?command=mmap§ion=2
> indicates MAP_ANONYMOUS is an alias for MAP_ANON and is provided for
> compatibility.
>
> https://man.openbsd.org/mmap.2 also knows MAP_ANONYMOUS as a synonym.
>
> https://www.unix.com/man-page/osx/2/mmap/ does not know MAP_ANONYMOUS.
>
> So shouldn't the man page indicate that MAP_ANON is to be favored to
> write portable code? And correspondingly mark MAP_ANONYMOUS as synonym
> only kept for compatibility.
>
> The Open Group Base Specifications Issue 7, 2018 Edition does not
> reference either of both. So both values are not POSIX but it is not
> correct to describe them as Linux only.
The text saying that MAP_ANON is deprecated is ancient (at least
20 years old). I don't know why that text was added.
Things are not simple though: it looks like there's at least
one historical implementation (HP-US) that defines MAP_ANONYMOUS
but not MAP_ANON.
I've applied the patch below.
Reported-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reword a little to allow for the fact that there are now
*two* reasons to consider using this flag.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Since introduction of MAP_SHARED_VALIDATE, in case flags contain
both MAP_PRIVATE and MAP_SHARED, mmap() doesn't fail with EINVAL,
it succeeds.
The reason for that is that MAP_SHARED_VALIDATE is in fact equal
to MAP_PRIVATE | MAP_SHARED.
This is intended behavior, see:
https://lwn.net/Articles/758594/https://lwn.net/Articles/758598/
Signed-off-by: Nikola Forró <nforro@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
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>
The current manpage reads to me as if the kernel will always pick
a free space close to the requested address, but that's not the
case:
mmap(0x600000000000, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS,
-1, 0) = 0x600000000000
mmap(0x600000000000, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS,
-1, 0) = 0x7f5042859000
You can also see this in the various implementations of
->get_unmapped_area() - if the specified address isn't available,
the kernel basically ignores the hint (apart from the 5level
paging hack).
Clarify how this works a bit.
Acked-by: Michal Hocko <mhocko@suse.com>
Signed-off-by: Jann Horn <jannh@google.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
I regularly see excessive fd usage bugs (or even leaks) caused by
people who think they need to keep the fd open as long as the
mapping exists.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This text has become rather long, making it it somewhat
unwieldy in the discussion of the mmap() flags. Therefore,
move it to NOTES, with a pointer in DESCRIPTION referring
the reader to NOTES.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Change "extremely hazardous" to "hazardous". The former phrasing
is a little overwrought; on its own "hazardous" is enough to
convey the sense of danger.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Clarify that MAP_FIXED is appropriate if the specified address
range has been reserved using an existing mapping, but shouldn't
be used otherwise.
Signed-off-by: Jann Horn <jannh@google.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reviewed-by: Ross Zwisler <ross.zwisler@linux.intel.com>
Signed-off-by: Jan Kara <jack@suse.cz>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In Linux 2..0, do_mmap() had the following check:
if (flags & MAP_DENYWRITE) {
if (file->f_inode->i_writecount > 0)
return -ETXTBSY;
}
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>