Tweak the @manpageurl macro to customize the output for
each of html, info, and pdf output. HTML and PDF (at
least, these days) support clicking on the link title,
whereas info does not. Add text to the intro section
explaining which man pages are normative and which
aren't.
The POSIX Semaphores functions are currently undocumented in our info
pages. This commit adds links to the man-pages documentation for all
the `sem_*' functions (except `sem_clockwait') so that they refer to
some useful documentation instead of just being stubs. `sem_clockwait'
isn't documented by man-pages but thankfully already has a small useful
blurb in our own docs.
Reviewed-by: Adhemerval Zanella <adhemerval.zanella@linaro.org>
This commit moves the `sem_*' family of functions from the IPC chapter,
replacing them with a reference to their new location in the Threads
chapter. `sem_clockwait' is also moved out of the Non-POSIX Extensions
subsection since it is now included in the standard since Issue 8:
https://pubs.opengroup.org/onlinepubs/9799919799/functions/sem_clockwait.html
Reviewed-by: Adhemerval Zanella <adhemerval.zanella@linaro.org>
Operation systems which represent text files in a line-oriented
fashion (and not as byte streams with a character sequence reserved
for line termination) logically cannot flush a buffer without
also creating a terminated line.
Update this portability note and move it to the Binary Streams
section. Add another related compatibility concern, too.
Linux 6.13 was released with a change that overwrites those bytes.
This means that the check_unused subtest fails.
Update the manual accordingly.
Tested-by: Xi Ruoyao <xry111@xry111.site>
Reviewed-by: Adhemerval Zanella <adhemerval.zanella@linaro.org>
This tunable controls Guarded Control Stack (GCS) for the process.
0 = disabled: do not enable GCS
1 = enforced: check markings and fail if any binary is not marked
2 = optional: check markings but keep GCS off if a binary is unmarked
3 = override: enable GCS, markings are ignored
By default it is 0, so GCS is disabled, value 1 will enable GCS.
The status is stored into GL(dl_aarch64_gcs) early and only applied
later, since enabling GCS is tricky: it must happen on a top level
stack frame. Using GL instead of GLRO because it may need updates
depending on loaded libraries that happen after readonly protection
is applied, however library marking based GCS setting is not yet
implemented.
Describe new tunable in the manual.
Co-authored-by: Yury Khrustalev <yury.khrustalev@arm.com>
Reviewed-by: Adhemerval Zanella <adhemerval.zanella@linaro.org>
The new tunable can be used to control whether executable stacks are
allowed from either the main program or dependencies. The default is
to allow executable stacks.
The executable stacks default permission is checked agains the one
provided by the PT_GNU_STACK from program headers (if present). The
tunable also disables the stack permission change if any dependency
requires an executable stack at loading time.
Checked on x86_64-linux-gnu, i686-linux-gnu, and aarch64-linux-gnu.
Reviewed-by: Florian Weimer <fweimer@redhat.com>
Also document C and C++ compilers used to test glibc should come from
the same set of compilers.
Signed-off-by: H.J. Lu <hjl.tools@gmail.com>
Reviewed-by: Sam James <sam@gentoo.org>
C23 adds various <math.h> function families originally defined in TS
18661-4. Add the atan2pi functions (atan2(y,x)/pi).
Tested for x86_64 and x86, and with build-many-glibcs.py.
C23 adds various <math.h> function families originally defined in TS
18661-4. Add the atanpi functions (atan(x)/pi).
Tested for x86_64 and x86, and with build-many-glibcs.py.
Support testing glibc build with a different C compiler or a different
C++ compiler with
$ ../glibc-VERSION/configure TEST_CC="gcc-6.4.1" TEST_CXX="g++-6.4.1"
1. Add LIBC_TRY_CC_AND_TEST_CC_OPTION, LIBC_TRY_CC_AND_TEST_CC_COMMAND
and LIBC_TRY_CC_AND_TEST_LINK to test both CC and TEST_CC.
2. Add check and xcheck targets to Makefile.in and override build compiler
options with ones from TEST_CC and TEST_CXX.
Tested on Fedora 41/x86-64:
1. Building with GCC 14.2.1 and testing with GCC 6.4.1 and GCC 11.2.1.
2. Building with GCC 15 and testing with GCC 6.4.1.
Support for GCC versions older than GCC 6.2 may need to change the test
sources. Other targets may need to update configure.ac under sysdeps and
modify Makefile.in to override target build compiler options.
Signed-off-by: H.J. Lu <hjl.tools@gmail.com>
Reviewed-by: Sam James <sam@gentoo.org>
C23 adds various <math.h> function families originally defined in TS
18661-4. Add the asinpi functions (asin(x)/pi).
Tested for x86_64 and x86, and with build-many-glibcs.py.
C23 adds various <math.h> function families originally defined in TS
18661-4. Add the acospi functions (acos(x)/pi).
Tested for x86_64 and x86, and with build-many-glibcs.py.
C23 adds various <math.h> function families originally defined in TS
18661-4. Add the tanpi functions (tan(pi*x)).
Tested for x86_64 and x86, and with build-many-glibcs.py.
C23 adds various <math.h> function families originally defined in TS
18661-4. Add the sinpi functions (sin(pi*x)).
Tested for x86_64 and x86, and with build-many-glibcs.py.
C23 adds various <math.h> function families originally defined in TS
18661-4. Add the cospi functions (cos(pi*x)).
Tested for x86_64 and x86, and with build-many-glibcs.py.
This does not describe how to use RTLD_DI_ORIGIN and l_name
to reconstruct a full path for the an object. The reason
is that I think we should not recommend further use of
RTLD_DI_ORIGIN due to its buffer overflow potential (bug 24298).
This should be covered by another dlinfo extension. It would
also obsolete the need for the dladdr approach to obtain
the file name for the main executable.
Obtaining the lowest address from load segments in program
headers is quite clumsy and should be provided directly
via dlinfo.
Reviewed-by: Carlos O'Donell <carlos@redhat.com>
Describe AArch64 specific flags PKEY_DISABLE_READ and PKEY_DISABLE_EXECUTE that
are available on AArch64 systems with enabled Stage 1 permission overlays
feature introduced in Armv8.9 / 9.4 (FEAT_S1POE).
Reviewed-by: Adhemerval Zanella <adhemerval.zanella@linaro.org>
Update the name of the argument in several pkey_*() functions that refers
to access restrictions rather than access rights: change access "rights"
to access "restrictions".
Specify that the result of the pkey_get() should be checked using bitwise
operations rather than plain equals comparison.
Reviewed-by: Adhemerval Zanella <adhemerval.zanella@linaro.org>
This patch starts preparation for C2Y support in glibc headers by
adding a feature test macro _ISOC2Y_SOURCE and corresponding
__GLIBC_USE (ISOC2Y). (I mostly copied the work of Joseph Myers
for C2X). As with other such macros, C2Y features are also
enabled by compiling for a standard newer than C23, or by using
_GNU_SOURCE.
This patch does not itself enable anything new in the headers for C2Y;
that is to be done in followup patches. (For example an implementation
of WG14 N3349.)
Once C2Y becomes an actual standard we'll presumably move to using the
actual year in the feature test macro and __GLIBC_USE, with some
period when both macro spellings are accepted, as was done with
_ISOC2X_SOURCE.
Tested for x86_64.
Signed-off-by: Lenard Mollenkopf <glibc@lenardmollenkopf.de>
The gilbc manual has some documentation in llio.texi of requirements
for moving between I/O on FILE * streams and file descriptors on the
same open file description.
The documentation of what must be done on a FILE * stream to move from
it to either a file descriptor or another FILE * for the same open
file description seems to match POSIX. However, there is an
additional requirement in POSIX on the *second* of the two handles
being moved between, which is not mentioned in the glibc manual: "If
any previous active handle has been used by a function that explicitly
changed the file offset, except as required above for the first
handle, the application shall perform an lseek() or fseek() (as
appropriate to the type of handle) to an appropriate location.".
Document this requirement on seeking in the glibc manual, limited to
the case that seems relevant to glibc (the new channel is a previously
active stream, on which the seeking previously occurred). Note that
I'm not sure what the "except as required above for the first handle"
is meant to be about, so I haven't documented anything for it. As far
as I can tell, nothing specified for moving from the first handle
actually list calling a seek function as one of the steps to be done.
(Current POSIX doesn't seem to have any relevant rationale for this
section. The rationale in the 1996 edition says "In requiring the
seek to an appropriate location for the new handle, the application is
required to know what it is doing if it is passing streams with seeks
involved. If the required seek is not done, the results are undefined
(and in fact the program probably will not work on many common
implementations)." - which also doesn't help in understanding the
purpose of "except as required above for the first handle".)
Tested with "make info" and "make pdf".
Glibc has two gnu-extension functions that are implemented as
macros but not documented as such: fread_unlocked and
fwrite_unlocked. Document them as such.
Additionally, putc_unlocked and getc_unlocked are documented in
POSIX as possibly being macros. Update the manual to add a warning
about those also, depite glibc not implementing them as macros.
The manual contained several instances of incorrect formatting
that were correct texinfo but produced incorrectly rendered manuals
or incorrect behaviour from the tooling.
The most important was incorrect quoting of function returns
by failing to use {} to quote the return. The impact of this
mistake means that 'info libc func' does not jump to the function
in question but instead to the introductory page under the assumption
that func doesn't exist. The function returns are now correctly
quoted.
The second issue was the use of a category specifier with
@deftypefun which doesn't accept a category specifier. If a category
specifier is required then @deftypefn needs to be used. This is
corrected by changing the command to @deftypefn for such functions
that used {Deprecated function} as a category.
The last issue is a missing space between the function name and the
arguments which results in odd function names like "epoll_wait(int"
instead of "epoll_wait". This also impacts the use of 'info libc'
and is corrected.
We additionally remove ';' from the end of function arguments and
add an 'int' return type for dprintf.
Lastly we add a new test check-deftype.sh which verifies the expected
formatting of @deftypefun, @deftypefunx, @deftypefn, and
@deftypefnx. The new test is also run as the summary file is
generated to ensure we don't generate incorrect results.
The existing check-safety.sh is also run directly as a test to increase
coverage since the existing tests only ran on manual install.
The new tests now run as part of the standard "make check" that
pre-commit CI runs and developers should run.
No regressions on x86_64.
HTML and PDF rendering reviewed and looks correct for all changes.
Reviewed-by: H.J. Lu <hjl.tools@gmail.com>
Linux 6.11 adds the new flag for pwritev2 (commit
c34fc6f26ab86d03a2d47446f42b6cd492dfdc56).
Checked on x86_64-linux-gnu on 6.11 kernel.
Reviewed-by: H.J. Lu <hjl.tools@gmail.com>
This request the page to be never written out to swap, it will be zeroed
under memory pressure (so kernel can just drop the page), it is inherited
by fork, it is not counted against @code{mlock} budget, and if there is
no enough memory to service a page faults there is no fatal error (so not
signal is sent).
Tested with build-many-glibcs.py.
Reviewed-by: H.J. Lu <hjl.tools@gmail.com>
The recursive lock used on abort does not synchronize with a new process
creation (either by fork-like interfaces or posix_spawn ones), nor it
is reinitialized after fork().
Also, the SIGABRT unblock before raise() shows another race condition,
where a fork or posix_spawn() call by another thread, just after the
recursive lock release and before the SIGABRT signal, might create
programs with a non-expected signal mask. With the default option
(without POSIX_SPAWN_SETSIGDEF), the process can see SIG_DFL for
SIGABRT, where it should be SIG_IGN.
To fix the AS-safe, raise() does not change the process signal mask,
and an AS-safe lock is used if a SIGABRT is installed or the process
is blocked or ignored. With the signal mask change removal,
there is no need to use a recursive loc. The lock is also taken on
both _Fork() and posix_spawn(), to avoid the spawn process to see the
abort handler as SIG_DFL.
A read-write lock is used to avoid serialize _Fork and posix_spawn
execution. Both sigaction (SIGABRT) and abort() requires to lock
as writer (since both change the disposition).
The fallback is also simplified: there is no need to use a loop of
ABORT_INSTRUCTION after _exit() (if the syscall does not terminate the
process, the system is broken).
The proposed fix changes how setjmp works on a SIGABRT handler, where
glibc does not save the signal mask. So usage like the below will now
always abort.
static volatile int chk_fail_ok;
static jmp_buf chk_fail_buf;
static void
handler (int sig)
{
if (chk_fail_ok)
{
chk_fail_ok = 0;
longjmp (chk_fail_buf, 1);
}
else
_exit (127);
}
[...]
signal (SIGABRT, handler);
[....]
chk_fail_ok = 1;
if (! setjmp (chk_fail_buf))
{
// Something that can calls abort, like a failed fortify function.
chk_fail_ok = 0;
printf ("FAIL\n");
}
Such cases will need to use sigsetjmp instead.
The _dl_start_profile calls sigaction through _profil, and to avoid
pulling abort() on loader the call is replaced with __libc_sigaction.
Checked on x86_64-linux-gnu and aarch64-linux-gnu.
Reviewed-by: DJ Delorie <dj@redhat.com>
This is not completely clear from the C standard (although there
is footnote number 289 in C11), but I assume that our implementation
works this way.
Reviewed-by: DJ Delorie <dj@redhat.com>
The __is_last field was replaced with a bitmask in
commit 85830c4c46 in 2000,
and multiple bits are in use today.
Reviewed-by: DJ Delorie <dj@redhat.com>
And struct sched_attr.
In sysdeps/unix/sysv/linux/bits/sched.h, the hack that defines
sched_param around the inclusion of <linux/sched/types.h> is quite
ugly, but the definition of struct sched_param has already been
dropped by the kernel, so there is nothing else we can do and maintain
compatibility of <sched.h> with a wide range of kernel header
versions. (An alternative would involve introducing a separate header
for this functionality, but this seems unnecessary.)
The existing sched_* functions that change scheduler parameters
are already incompatible with PTHREAD_PRIO_PROTECT mutexes, so
there is no harm in adding more functionality in this area.
The documentation mostly defers to the Linux manual pages.
Reviewed-by: Carlos O'Donell <carlos@redhat.com>
From the existing @manpagefunctionstub{func,sec} macro,
so that URLs can be included in the manual without the
stub text.
Reviewed-by: Carlos O'Donell <carlos@redhat.com>
As recently discussed, document that freopen does not work with
streams opened with functions such as popen, fmemopen, open_memstream
or fopencookie. I've filed
<https://austingroupbugs.net/view.php?id=1855> to clarify this issue
in POSIX.
Tested with "make info" and "make html".
Reference this new section from the O_PATH documentation.
And document the functions openat, openat64, fstatat, fstatat64.
(The safety assessment for fstatat was already obsolete because
current glibc assumes kernel support for the underlying system
call.)
Reviewed-by: Adhemerval Zanella <adhemerval.zanella@linaro.org>
When ungetc is called on an unused stream, the backup buffer is
allocated without the main get area being present. This results in
every subsequent ungetc (as the stream remains in the backup area)
checking uninitialized memory in the backup buffer when trying to put a
character back into the stream.
Avoid comparing the input character with buffer contents when in backup
to avoid this uninitialized read. The uninitialized read is harmless in
this context since the location is promptly overwritten with the input
character, thus fulfilling ungetc functionality.
Also adjust wording in the manual to drop the paragraph that says glibc
cannot do multiple ungetc back to back since with this change, ungetc
can actually do this.
Signed-off-by: Siddhesh Poyarekar <siddhesh@sourceware.org>
Reviewed-by: Carlos O'Donell <carlos@redhat.com>
This is a follow-up to 10de4a47ef that
reworded the manual entries for putc and putwc and removed any
performance claims.
This commit further clarifies these entries and brings getc and getwc in
line with the descriptions of putc and putwc, removing any performance
claims from them as well.
Reviewed-by: Florian Weimer <fweimer@redhat.com>
The existing description for setrlimit() has some ambiguity. It could be
understood to have the semantics of getrlimit(), i.e., the limits from the
process are stored in the provided rlp pointer.
Make the description more explicit that rlp are the input values, and that
the limits of the process is changed with this function.
Reviewed-by: Florian Weimer <fweimer@redhat.com>
The manual entry for `putc' described what "most systems" do instead of
describing the glibc implementation and its guarantees. This commit
fixes that by warning that putc may be implemented as a macro that
double-evaluates `stream', and removing the performance claim.
Even though the current `putc' implementation does not double-evaluate
`stream', offering this obscure guarantee as an extension to what
POSIX allows does not seem very useful.
The entry for `putwc' is also edited to bring it in line with `putc'.
Reviewed-by: Florian Weimer <fweimer@redhat.com>
DJ Delorie
Tulio Magno Quites Machado Filho
Arjun Shankar
Florian Weimer
Andreas K. Hüttel
Szabolcs Nagy
Paul Eggert
Adhemerval Zanella
H.J. Lu
Joseph Myers
Yury Khrustalev
Jonathan Wakely
Lenard Mollenkopf
Carlos O'Donell
Siddhesh Poyarekar
Lukas Bulwahn