From e5b1c0fa4ff21185b29fd4202407bbde37478c91 Mon Sep 17 00:00:00 2001 From: Petr Vorel Date: Tue, 13 Jan 2026 12:36:08 +0100 Subject: Documentation: Remove :manpage: from non-existing man pages Removing :manpage: from non-existing man pages (xyzzy(2), xyzzyat(2), fxyzzy(3) in adding-syscalls.rst, including translations) prevent adding link to nonexisting man pages when using manpages_url in next commit. While at it, add also missing '(2)' in sp_SP translation. Reviewed-by: Alejandro Colomar Signed-off-by: Petr Vorel Signed-off-by: Jonathan Corbet Message-ID: <20260113113612.315748-2-pvorel@suse.cz> --- Documentation/process/adding-syscalls.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'Documentation/process/adding-syscalls.rst') diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst index fc0b0bbcd34d..e8892f03eadd 100644 --- a/Documentation/process/adding-syscalls.rst +++ b/Documentation/process/adding-syscalls.rst @@ -111,7 +111,7 @@ should use a file descriptor as the handle for that object -- don't invent a new type of userspace object handle when the kernel already has mechanisms and well-defined semantics for using file descriptors. -If your new :manpage:`xyzzy(2)` system call does return a new file descriptor, +If your new xyzzy(2) system call does return a new file descriptor, then the flags argument should include a value that is equivalent to setting ``O_CLOEXEC`` on the new FD. This makes it possible for userspace to close the timing window between ``xyzzy()`` and calling @@ -127,18 +127,18 @@ descriptor. Making a file descriptor ready for reading or writing is the normal way for the kernel to indicate to userspace that an event has occurred on the corresponding kernel object. -If your new :manpage:`xyzzy(2)` system call involves a filename argument:: +If your new xyzzy(2) system call involves a filename argument:: int sys_xyzzy(const char __user *path, ..., unsigned int flags); -you should also consider whether an :manpage:`xyzzyat(2)` version is more appropriate:: +you should also consider whether an xyzzyat(2) version is more appropriate:: int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags); This allows more flexibility for how userspace specifies the file in question; in particular it allows userspace to request the functionality for an already-opened file descriptor using the ``AT_EMPTY_PATH`` flag, effectively -giving an :manpage:`fxyzzy(3)` operation for free:: +giving an fxyzzy(3) operation for free:: - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...) - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...) @@ -147,11 +147,11 @@ giving an :manpage:`fxyzzy(3)` operation for free:: :manpage:`openat(2)` man page; for an example of AT_EMPTY_PATH, see the :manpage:`fstatat(2)` man page.) -If your new :manpage:`xyzzy(2)` system call involves a parameter describing an +If your new xyzzy(2) system call involves a parameter describing an offset within a file, make its type ``loff_t`` so that 64-bit offsets can be supported even on 32-bit architectures. -If your new :manpage:`xyzzy(2)` system call involves privileged functionality, +If your new xyzzy(2) system call involves privileged functionality, it needs to be governed by the appropriate Linux capability bit (checked with a call to ``capable()``), as described in the :manpage:`capabilities(7)` man page. Choose an existing capability bit that governs related functionality, @@ -160,7 +160,7 @@ under the same bit, as this goes against capabilities' purpose of splitting the power of root. In particular, avoid adding new uses of the already overly-general ``CAP_SYS_ADMIN`` capability. -If your new :manpage:`xyzzy(2)` system call manipulates a process other than +If your new xyzzy(2) system call manipulates a process other than the calling process, it should be restricted (using a call to ``ptrace_may_access()``) so that only a calling process with the same permissions as the target process, or with the necessary capabilities, can @@ -196,7 +196,7 @@ be cc'ed to linux-api@vger.kernel.org. Generic System Call Implementation ---------------------------------- -The main entry point for your new :manpage:`xyzzy(2)` system call will be called +The main entry point for your new xyzzy(2) system call will be called ``sys_xyzzy()``, but you add this entry point with the appropriate ``SYSCALL_DEFINEn()`` macro rather than explicitly. The 'n' indicates the number of arguments to the system call, and the macro takes the system call name -- cgit v1.2.3 From 78a00cac1e962aacfe67ffa0ce295e709e0e6c5b Mon Sep 17 00:00:00 2001 From: Rhys Tumelty Date: Wed, 28 Jan 2026 22:02:31 +0000 Subject: docs: fix 're-use' -> 'reuse' in documentation Signed-off-by: Rhys Tumelty Acked-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20260128220233.179439-1-rhys@tumelty.co.uk> --- Documentation/process/adding-syscalls.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/process/adding-syscalls.rst') diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst index e8892f03eadd..91fc88681b1e 100644 --- a/Documentation/process/adding-syscalls.rst +++ b/Documentation/process/adding-syscalls.rst @@ -117,7 +117,7 @@ then the flags argument should include a value that is equivalent to setting the timing window between ``xyzzy()`` and calling ``fcntl(fd, F_SETFD, FD_CLOEXEC)``, where an unexpected ``fork()`` and ``execve()`` in another thread could leak a descriptor to -the exec'ed program. (However, resist the temptation to re-use the actual value +the exec'ed program. (However, resist the temptation to reuse the actual value of the ``O_CLOEXEC`` constant, as it is architecture-specific and is part of a numbering space of ``O_*`` flags that is fairly full.) @@ -459,7 +459,7 @@ the compatibility wrapper:: ... 555 x32 xyzzy __x32_compat_sys_xyzzy -If no pointers are involved, then it is preferable to re-use the 64-bit system +If no pointers are involved, then it is preferable to reuse the 64-bit system call for the x32 ABI (and consequently the entry in arch/x86/entry/syscalls/syscall_64.tbl is unchanged). -- cgit v1.2.3