Format only one man page cross reference per input line.
Begin parentheticals on their own input lines.
Also, groff 1.23.0's (and Plan 9 from User Space's) `MR` is not a font
style alternation macro; there is no "reversed" form as with `BR` and
`RB`. So when a man page cross reference must be immediately preceded
by punctuation, put that punctuation on the previous text line and use
the `\c` escape sequence to connect them.
Elliott Hughes [Tue, 14 Nov 2023 00:46:43 +0000 (16:46 -0800)]
ffs.3: All these functions live in <strings.h>.
In most cases you'll get them transitively through <string.h>, but it's
misleading for the man page to claim that they're _in_ <string.h>, and
especially weird to claim they're in _different_ headers from each
other!
This is also true of Apple's headers, and FreeBSD (the other BSDs only
have ffs(), not its siblings).
Paul Eggert [Mon, 13 Nov 2023 22:26:42 +0000 (14:26 -0800)]
string.3: strncpy(): wfix
Say "size" not "width" for byte counts; "width" is for the number of
bits in a word. Say "leading" to make it clear we don’t care about what
the source contains after its first null byte.
string.3: strncpy(): Talk about bytes, not characters
These functions are also the way to copy multibyte strings, so be
generic and say that they just copy bytes. Not every byte is a valid
character in (for example) UTF-8 locales.
Cowritten-by: Paul Eggert <eggert@cs.ucla.edu> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Add this new truncating string-copying function. It intends to fully
replace strlcpy(3), which has important bugs (documented in the
preceeding commit).
It is almost identical to Linux kernel's strscpy(9), so reduce the
documentation of strscpy(9) in this page to the minimum, giving
preference to strtcpy(3). Provide a reference implementation, since no
libc provides it.
Providing an easy, safe, and relatively fast truncating string-copying
function should prevent users from rolling their own, in which they
might introduce bugs accidentally. We already made enough mistakes
while discussing these functions, so it's certainly not something that
should be written often.
Cc: Paul Eggert <eggert@cs.ucla.edu> Cc: Jonny Grant <jg@jguk.org> Cc: DJ Delorie <dj@redhat.com> Cc: Matthew House <mattlloydhouse@gmail.com> Cc: Oskari Pirhonen <xxc3ncoredxx@gmail.com> Cc: Thorsten Kukuk <kukuk@suse.com> Cc: Adhemerval Zanella Netto <adhemerval.zanella@linaro.org> Cc: Zack Weinberg <zack@owlfolio.org> Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com> Cc: Carlos O'Donell <carlos@redhat.com> Cc: Xi Ruoyao <xry111@xry111.site> Cc: Stefan Puiu <stefan.puiu@gmail.com> Cc: Andreas Schwab <schwab@linux-m68k.org> Cc: Guillem Jover <guillem@hadrons.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Also point to BUGS from other sections that talk about these functions.
These functions are doomed due to the design decision of mirroring
snprintf(3)'s return value. They must return strlen(src), which makes
them terribly slow, and vulnerable to DoS if an attacker can control
strlen(src).
A better design would have been to return -1 when truncating.
Reported-by: Paul Eggert <eggert@cs.ucla.edu> Cc: Jonny Grant <jg@jguk.org> Cc: DJ Delorie <dj@redhat.com> Cc: Matthew House <mattlloydhouse@gmail.com> Cc: Oskari Pirhonen <xxc3ncoredxx@gmail.com> Cc: Thorsten Kukuk <kukuk@suse.com> Cc: Adhemerval Zanella Netto <adhemerval.zanella@linaro.org> Cc: Zack Weinberg <zack@owlfolio.org> Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com> Cc: Carlos O'Donell <carlos@redhat.com> Cc: Xi Ruoyao <xry111@xry111.site> Cc: Stefan Puiu <stefan.puiu@gmail.com> Cc: Andreas Schwab <schwab@linux-m68k.org> Cc: Guillem Jover <guillem@hadrons.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
string_copying.7: BUGS: *cat(3) functions aren't always bad
The compiler will sometimes optimize them to normal *cpy(3) functions,
since the length of dst is usually known, if the previous *cpy(3) is
visible to the compiler. And they provide for cleaner code. If you
know that they'll get optimized, you could use them.
Cc: Paul Eggert <eggert@cs.ucla.edu> Cc: Jonny Grant <jg@jguk.org> Cc: DJ Delorie <dj@redhat.com> Cc: Matthew House <mattlloydhouse@gmail.com> Cc: Oskari Pirhonen <xxc3ncoredxx@gmail.com> Cc: Thorsten Kukuk <kukuk@suse.com> Cc: Adhemerval Zanella Netto <adhemerval.zanella@linaro.org> Cc: Zack Weinberg <zack@owlfolio.org> Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com> Cc: Carlos O'Donell <carlos@redhat.com> Cc: Xi Ruoyao <xry111@xry111.site> Cc: Stefan Puiu <stefan.puiu@gmail.com> Cc: Andreas Schwab <schwab@linux-m68k.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
stpncpy.3, string.3, string_copying.7: Clarify that st[rp]ncpy() pad with null bytes
The previous wording could be interpreted as if the nulls were already
in place. Clarify that it's this function which pads with null bytes.
Also, it copies "characters" from the src string. That's a bit more
specific than copying "bytes", and makes it clearer that the terminating
null byte in src is not part of the copy.
Suggested-by: Jonny Grant <jg@jguk.org> Cc: DJ Delorie <dj@redhat.com> Cc: Matthew House <mattlloydhouse@gmail.com> Cc: Oskari Pirhonen <xxc3ncoredxx@gmail.com> Cc: Thorsten Kukuk <kukuk@suse.com> Cc: Adhemerval Zanella Netto <adhemerval.zanella@linaro.org> Cc: Zack Weinberg <zack@owlfolio.org> Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com> Cc: Carlos O'Donell <carlos@redhat.com> Cc: Paul Eggert <eggert@cs.ucla.edu> Cc: Xi Ruoyao <xry111@xry111.site> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Fixes: 17282a589f2f ("posixoptions.7: Make function lists more consistent and less cluttered") Reported-by: Helge Kreutzmann <debian@helgefjell.de> Cc: Mario Blaettermann <mario.blaettermann@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Bruno Haible [Sun, 29 Oct 2023 20:46:49 +0000 (21:46 +0100)]
prctl.2: Use a better term
The first argument of prctl() was denoted as "option" here. This makes
no sense, because
- The first argument is not optional; it is mandatory.
A choice is an "option" only if it is possible to choose none of
the available choices.
- The title of the page is "operations on a process or thread".
A better term is "operation".
Cc: Stefan Puiu <stefan.puiu@gmail.com> Acked-by: Elliott Hughes <enh@google.com> Signed-off-by: Bruno Haible <bruno@clisp.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
The feature was added on glibc 2.33 as a way to improve the path search,
since the legacy hardware capabilities combination scheme does not scale
properly with new hardware support. The legacy support was removed non
glibc 2.37, so it is the only scheme currently supported.
man*/: ffix (Place short options after long options)
This increases the chances that the paragraph will start in the same
line as the tag, wasting less vertical space.
The result seems visually better to me.
On Wed, Oct 25, 2023 at 09:11:03AM -0500, G. Branden Robinson wrote:
> I also like your suggestion that if we really want to economize on
> space, we could present a command's long option form before its short,
> old-style Unix synonym, which will work well when the short option (plus
> its argument, if any) fits within the space for the paragraph tag. This
> might be a good idea for another reason; in GNU user space, the long
> option is the much more self-documenting form, and the single-character
> option name a kind of "expert mode" alternative. As a general rule,
> when presenting technical material, one should not lead with "expert
> mode".
Don Brace [Wed, 25 Oct 2023 14:22:35 +0000 (09:22 -0500)]
smartpqi.4: HISTORYise sysfs entry "version"
Remove the "version" sysfs entry. This entry was changed into
two sysfs entries: driver_version and firmware_version by
patch "(6d90615f1346 scsi: smartpqi: add sysfs entries)" in Linus's
tree Aug 22 2019.
Add HISTORY section.
Enumerate old sysfs entries replaced by newer entries.
Don Brace [Tue, 24 Oct 2023 22:01:53 +0000 (17:01 -0500)]
smartpqi.4: Add device attributes
Add in some device level sysfs entry descriptions:
lunid
unique_id
path_info
raid_bypass_cnt
sas_ncq_prio_enable
These have already been provided by the driver.
Reviewed-by: Scott Benesh <scott.benesh@microchip.com> Reviewed-by: Scott Teel <scott.teel@microchip.com> Reviewed-by: Mike McGowen <mike.mcgowen@microchip.com> Reviewed-by: Kevin Barnett <kevin.barnett@microchip.com> Signed-off-by: Don Brace <don.brace@microchip.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Don Brace [Tue, 24 Oct 2023 22:01:51 +0000 (17:01 -0500)]
smartpqi.4: Say "volumes" instead of "drives"
Change the word "drives" to "volumes" to match our documentation and how
they are presented to SCSI Mid-layer: as "LOGICAL VOLUMES".
I.E.
[0:1:0:0] disk HP LOGICAL VOLUME 7.02 /dev/sdc
Reviewed-by: Scott Benesh <scott.benesh@microchip.com> Reviewed-by: Scott Teel <scott.teel@microchip.com> Reviewed-by: Mike McGowen <mike.mcgowen@microchip.com> Reviewed-by: Kevin Barnett <kevin.barnett@microchip.com> Signed-off-by: Don Brace <don.brace@microchip.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
When there are multiple tags for a paragraph, using a single TP and
separating the tags with commas makes the man(7) source more complex.
It also has a disadvantage: when searching through a manual page,
heuristics such as " --option" don't work so well.
By using GNU's TQ, we simplify the source of the pages, and improve the
ability to search them.
ld.so.8: Clarify LD_PROFILE in secure-execution mode
Different than specified, glibc 2.2.5 does not ignore LD_PROFILE in
secure-execution mode. Instead, it uses the default LD_PROFILE_OUTPUT
(/var/profile) folder.
Axel Rasmussen [Tue, 17 Oct 2023 23:01:08 +0000 (16:01 -0700)]
ioctl_userfaultfd.2: Clarify the state of the uffdio_api structure on error
The old FIXME noted that the zeroing was done to differentiate the two
EINVAL cases. It's possible something like this was true historically,
but in current Linux we zero it in *both* EINVAL cases, so this is at
least no longer true.
After reading the code, I can't determine any clear reason why we zero
it in some cases but not in others. So, some simple advice we can give
userspace is: if an error occurs, treat the contents of the structure as
unspecified. Just re-initialize it before retrying UFFDIO_API again.
Reviewed-by: Mike Rapoport (IBM) <rppt@kernel.org> Cc: Peter Xu <peterx@redhat.com> Signed-off-by: Axel Rasmussen <axelrasmussen@google.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Matthew House [Sun, 15 Oct 2023 00:50:27 +0000 (20:50 -0400)]
fanotify.7: Fix field name in struct fanotify_event_info_fid
The final field of this struct as defined in include/uapi/linux/fanotify.h
(and as used in the example program) is called handle, not file_handle.
Fix this, and also replace the zero-length array with a flexible array
member to match the definition in the header.
Fixes: 0a4db6dc742d ("fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_REPORT_FID and directory modification events") Signed-off-by: Matthew House <mattlloydhouse@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Don Brace [Wed, 11 Oct 2023 19:00:23 +0000 (14:00 -0500)]
smartpqi.4: Add host attributes
Add in some host level sysfs entries:
enable_stream_detection - Send RAID 5/6 writes down the normal I/O path.
Allow for full-stripe write requests.
ssd_smart_path_enabled - Indicates that our Accelerated I/O (AIO) path
is enabled (AIO).
enable_r5_writes - Allow RAID 5 write operations down the AIO path.
enable_r6_writes - Allow RAID 6 write operations down the AIO path.
Reviewed-by: Scott Benesh <scott.benesh@microchip.com> Reviewed-by: Scott Teel <scott.teel@microchip.com> Reviewed-by: Mike McGowen <mike.mcgowen@microchip.com> Reviewed-by: Kevin Barnett <kevin.barnett@microchip.com> Signed-off-by: Don Brace <don.brace@microchip.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Rik van Riel [Thu, 12 Oct 2023 01:46:52 +0000 (21:46 -0400)]
execve.2: execve() also returns E2BIG if a string is too long
The execve syscall returns -E2BIG in 3 cases:
- The total length of the command line arguments and environment is too
large.
- An argument or environment string (including the NUL byte) is longer
than MAX_ARG_STRLEN.
- The full path to the executable (including the NUL byte) exceeds
MAX_ARG_STRLEN.
Spell out all 3 cases in the -E2BIG section.
Discovered by moving a too large commandline parameter to an environment
variable, and finding that things still did not work. Examined the code
in fs/exec.c to get the details.
This simple shell script starts failing at 2^17 on a system with 4kB
page size:
#!/bin/sh
STRING="a"
for loop in `seq 20`; do
STRING="$STRING$STRING"
export STRING
if /bin/true ; then
: # still under the limit
else
echo "fork failed at loop $loop"
fi
done
./exec2big.sh: line 10: /bin/true: Argument list too long
fork failed at loop 17
Suggested-by: Matthew House <mattlloydhouse@gmail.com> Signed-off-by: Rik van Riel <riel@surriel.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Don Brace [Tue, 3 Oct 2023 19:54:35 +0000 (14:54 -0500)]
smartpqi.4: FILES: wfix: Change "Logical drives" to "Disk drives" for /dev/sd*.
Reviewed-by: Scott Benesh <scott.benesh@microchip.com> Reviewed-by: Scott Teel <scott.teel@microchip.com> Reviewed-by: Mike McGowen <mike.mcgowen@microchip.com> Reviewed-by: Kevin Barnett <kevin.barnett@microchip.com> Signed-off-by: Don Brace <don.brace@microchip.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Allow user to change the length of time that the driver
will wait for the controller to become ready.
Reviewed-by: Scott Benesh <scott.benesh@microchip.com> Reviewed-by: Scott Teel <scott.teel@microchip.com> Reviewed-by: Mike McGowen <mike.mcgowen@microchip.com> Reviewed-by: Kevin Barnett <kevin.barnett@microchip.com> Signed-off-by: Don Brace <don.brace@microchip.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Axel Rasmussen [Tue, 3 Oct 2023 19:45:44 +0000 (12:45 -0700)]
ioctl_userfaultfd.2: Correct and update UFFDIO_API ioctl error codes
First, it is not correct that repeated UFFDIO_API calls result in
EINVAL. This is true *if both calls enable features*, but in the case
where we're doing a two-step feature detection handshake, the kernel
explicitly expects 2 calls (one with no features set). So, correct this
description.
Then, some new error cases have been added to the kernel recently, and
the man page wasn't updated to note these. So, add in descriptions of
these new error cases.
Signed-off-by: Axel Rasmussen <axelrasmussen@google.com> Cc: Peter Xu <peterx@redhat.com> Reviewed-by: Mike Rapoport (IBM) <rppt@kernel.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Fully describe how UFFDIO_API can be used to perform a two-step feature
handshake, and also note the case where this isn't necessary (programs
which don't depend on any extra features).
This lets us clean up an old FIXME asking for this to be described.
Signed-off-by: Axel Rasmussen <axelrasmussen@google.com> Cc: Peter Xu <peterx@redhat.com> Reviewed-by: Mike Rapoport (IBM) <rppt@kernel.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Replace blank lines by either a no-op '.', the dummy character '\&', or
an appropriate paragraphing macro. I've experimented with two '.' lines
before section headings, which may increase readability.
Xavier asked that his name be removed from the AUTHOR section, and since
we don't use that section in this project, we can just wipe it.
Add copyright notices to the pages, with Xavier as the original author,
and me, who will maintain them from now on. Xavier ACKed the
Linux-man-pages-copyleft license.
Adapt the TH line:
- Specify the date as (date).
- Specify the project name in the 4th arg.
- The first arg, the page name, must be the same as the file name.
pthread_cond_init.3, pthread_condattr_init.3, pthread_key_create.3, pthread_mutex_init.3, pthread_mutexattr_setkind_np.3, pthread_once.3: Update the glibc pages with the debian/glibc version of them
Import debian/local/manpages/pthread_*.3 git history from debian/glibc
I extracted the same pages that we imported from glibc, from the Debian
package history. They were imported from glibc to Debian, so we will be
able to pick those updates too. Below is the process.
Aurelien Jarno [Fri, 29 Nov 2013 11:00:45 +0000 (11:00 +0000)]
* Remove linuxthreads from the tarball:
- rules.d/tarball.mk: don't fetech linuxthreads and linuxthreads_db.
- rules.d/build.mk: don't build linuxthreads manpages.
- rules: don't run make clean in linuxthreads directory.
- patches/any/local-sysctl.diff: drop the linuxthreads part.
- patches/all/local-pthread-manpages.diff: remove.
- local/manpages/pthread_*.3: import the few remaining linuxthreads
manpages.
- debhelper.in/glibc-doc.manpages: update manpage locations.
projects / thirdparty / man-pages.git / log
