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>
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>
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".
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 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>
WG14 decided to use the name C23 as the informal name of the next
revision of the C standard (notwithstanding the publication date in
2024). Update references to C2X in glibc to use the C23 name.
This is intended to update everything *except* where it involves
renaming files (the changes involving renaming tests are intended to
be done separately). In the case of the _ISOC2X_SOURCE feature test
macro - the only user-visible interface involved - support for that
macro is kept for backwards compatibility, while adding
_ISOC23_SOURCE.
Tested for x86_64.
ISO C2x defines scanf length modifiers wN (for intN_t / int_leastN_t /
uintN_t / uint_leastN_t) and wfN (for int_fastN_t / uint_fastN_t).
Add support for those length modifiers, similar to the printf support
previously added.
Tested for x86_64 and x86.
ISO C2x defines scanf %b for input of binary integers (with an
optional 0b or 0B prefix). Implement such support, along with the
corresponding SCNb* macros in <inttypes.h>. Unlike the support for
binary integers with 0b or 0B prefix with scanf %i, this is supported
in all versions of scanf (independent of the standards mode used for
compilation), because there are no backwards compatibility concerns
(%b wasn't previously a supported format) the way there were for %i.
Tested for x86_64 and x86.
ISO C2x defines printf length modifiers wN (for intN_t / int_leastN_t
/ uintN_t / uint_leastN_t) and wfN (for int_fastN_t / uint_fastN_t).
Add support for those length modifiers (such a feature was previously
requested in bug 24466). scanf support is to be added separately.
GCC 13 has format checking support for these modifiers.
When used with the support for registering format specifiers, these
modifiers are translated to existing flags in struct printf_info,
rather than trying to add some way of distinguishing them without
breaking the printf_info ABI. C2x requires an error to be returned
for unsupported values of N; this is implemented for printf-family
functions, but the parse_printf_format interface doesn't support error
returns, so such an error gets discarded by that function.
Tested for x86_64 and x86.
WG14 recently accepted two additions to the printf/scanf %b/%B
support: there are now PRIb* and SCNb* macros in <inttypes.h>, and
printf %B is now an optional feature defined in normative text,
instead of recommended practice, with corresponding PRIB* macros that
can also be used to test whether that optional feature is supported.
See N3072 items 14 and 15 for details (those changes were accepted,
some other changes in that paper weren't).
Add the corresponding PRI* macros to glibc and update one place in the
manual referring to %B as recommended. (SCNb* should naturally be
added at the same time as the corresponding scanf %b support.)
Tested for x86_64 and x86.
C2x adds binary integer constants starting with 0b or 0B, and supports
those constants for the %i scanf format (in addition to the %b format,
which isn't yet implemented for scanf in glibc). Implement that scanf
support for glibc.
As with the strtol support, this is incompatible with previous C
standard versions, in that such an input string starting with 0b or 0B
was previously required to be parsed as 0 (with the rest of the input
potentially matching subsequent parts of the scanf format string).
Thus this patch adds 12 new __isoc23_* functions per long double
format (12, 24 or 36 depending on how many long double formats the
glibc configuration supports), with appropriate header redirection
support (generally very closely following that for the __isoc99_*
scanf functions - note that __GLIBC_USE (DEPRECATED_SCANF) takes
precedence over __GLIBC_USE (C2X_STRTOL), so the case of GNU
extensions to C89 continues to get old-style GNU %a and does not get
this new feature). The function names would remain as __isoc23_* even
if C2x ends up published in 2024 rather than 2023.
When scanf %b support is added, I think it will be appropriate for all
versions of scanf to follow C2x rules for inputs to the %b format
(given that there are no compatibility concerns for a new format).
Tested for x86_64 (full glibc testsuite). The first version was also
tested for powerpc (32-bit) and powerpc64le (stdio-common/ and wcsmbs/
tests), and with build-many-glibcs.py.
Always null-terminate the buffer and set E2BIG if the buffer is too
small. This fixes bug 27857.
Reviewed-by: Adhemerval Zanella <adhemerval.zanella@linaro.org>
The @refill command has been obsolete for a while and now texinfo has
started warning about it.
Reviewed-by: Florian Weimer <fweimer@redhat.com>
Signed-off-by: Siddhesh Poyarekar <siddhesh@sourceware.org>
%#m prints errno as an error constant if one is available, or
a decimal number as a fallback. This intends to address the gap
that strerrorname_np does not work well with printf for unknown
error codes due to its NULL return values in those cases.
Reviewed-by: Adhemerval Zanella <adhemerval.zanella@linaro.org>
C2X adds a printf %b format (see
<http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2630.pdf>, accepted
for C2X), for outputting integers in binary. It also has recommended
practice for a corresponding %B format (like %b, but %#B starts the
output with 0B instead of 0b). Add support for these formats to
glibc.
One existing test uses %b as an example of an unknown format, to test
how glibc printf handles unknown formats; change that to %v. Use of
%b and %B as user-registered format specifiers continues to work (and
we already have a test that covers that, tst-printfsz.c).
Note that C2X also has scanf %b support, plus support for binary
constants starting 0b in strtol (base 0 and 2) and scanf %i (strtol
base 0 and scanf %i coming from a previous paper that added binary
integer literals). I intend to implement those features in a separate
patch or patches; as discussed in the thread starting at
<https://sourceware.org/pipermail/libc-alpha/2020-December/120414.html>,
they will be more complicated because they involve adding extra public
symbols to ensure compatibility with existing code that might not
expect 0b constants to be handled by strtol base 0 and 2 and scanf %i,
whereas simply adding a new format specifier poses no such
compatibility concerns.
Note that the actual conversion from integer to string uses existing
code in _itoa.c. That code has special cases for bases 8, 10 and 16,
probably so that the compiler can optimize division by an integer
constant in the code for those bases. If desired such special cases
could easily be added for base 2 as well, but that would be an
optimization, not actually needed for these printf formats to work.
Tested for x86_64 and x86. Also tested with build-many-glibcs.py for
aarch64-linux-gnu with GCC mainline to make sure that the test does
indeed build with GCC 12 (where format checking warnings are enabled
for most of the test).
C2X adds a macro _PRINTF_NAN_LEN_MAX to <stdio.h>, giving the maximum
length of printf output for a NaN. glibc never includes an
n-char-sequence in its printf output for NaNs, so the correct value
for glibc is 4 ("-nan" or "-NAN"); define the macro accordingly.
This patch makes the macro definition conditional on __GLIBC_USE
(ISOC2X), as is generally done with features from new standard
versions. The name is in the implementation namespace for older
standards, so it would also be possible to define it unconditionally.
Tested for x86_64.
Cover key corner cases (e.g., whether errno is set) that are well
settled in glibc, fix some examples to avoid integer overflow, and
update some other dated examples (code needed for K&R C, e.g.).
* manual/charset.texi (Non-reentrant String Conversion):
* manual/filesys.texi (Symbolic Links):
* manual/memory.texi (Allocating Cleared Space):
* manual/socket.texi (Host Names):
* manual/string.texi (Concatenating Strings):
* manual/users.texi (Setting Groups):
Use reallocarray instead of realloc, to avoid integer overflow issues.
* manual/filesys.texi (Scanning Directory Content):
* manual/memory.texi (The GNU Allocator, Hooks for Malloc):
* manual/tunables.texi:
Use code font for 'malloc' instead of roman font.
(Symbolic Links): Don't assume readlink return value fits in 'int'.
* manual/memory.texi (Memory Allocation and C, Basic Allocation)
(Malloc Examples, Alloca Example):
* manual/stdio.texi (Formatted Output Functions):
* manual/string.texi (Concatenating Strings, Collation Functions):
Omit pointer casts that are needed only in ancient K&R C.
* manual/memory.texi (Basic Allocation):
Say that malloc sets errno on failure.
Say "convert" rather than "cast", since casts are no longer needed.
* manual/memory.texi (Basic Allocation):
* manual/string.texi (Concatenating Strings):
In examples, use C99 declarations after statements for brevity.
* manual/memory.texi (Malloc Examples): Add portability notes for
malloc (0), errno setting, and PTRDIFF_MAX.
(Changing Block Size): Say that realloc (p, 0) acts like
(p ? (free (p), NULL) : malloc (0)).
Add xreallocarray example, since other examples can use it.
Add portability notes for realloc (0, 0), realloc (p, 0),
PTRDIFF_MAX, and improve notes for reallocating to the same size.
(Allocating Cleared Space): Reword now-confusing discussion
about replacement, and xref "Replacing malloc".
* manual/stdio.texi (Formatted Output Functions):
Don't assume message size fits in 'int'.
* manual/string.texi (Concatenating Strings):
Fix undefined behavior involving arithmetic on a freed pointer.
A number of cross-references to the GCC info manual cause Texinfo
warnings; e.g.:
./creature.texi:11: warning: @xref node name should not contain `.'
This is due to "gcc.info" being used in the INFO-FILE-NAME (fourth)
argument. Changing it to "gcc" removes these warnings. (Manually
confirmed equivalent behaviour for make info, html, and pdf.)
* manual/creature.texi: Convert references to gcc.info to gcc.
* manual/stdio.texi: Likewise.
* manual/string.texi: Likewise.
The Summary is now generated from @standards, and syntax-checking is
performed. If invalid @standards syntax is detected, summary.pl will
fail, reporting all errors. Failure and error reporting is disabled
for now, however, since much of the manual is still incomplete
wrt. header and standards annotations.
Note that the sorting order of the Summary has changed; summary.pl
respects the locale, like summary.awk did, but the use of LC_ALL=C is
introduced in the Makefile. Other notable deviations are improved
detection of the annotated elements' names, which are used for
sorting, and improved detection of the @node used to reference into
the manual. The most noticeable difference in the rendered Summary is
that entries may now contain multiple lines, one for each header and
standard combination.
summary.pl accepts a `--help' option, which details the expected
syntax of @standards. If errors are reported, the user is directed to
this feature for further information.
* manual/Makefile: Generate summary.texi with summary.pl.
Force use of the C locale. Update Perl dependency comment.
* manual/header.texi: Update reference to summary.awk.
* manual/macros.texi: Refer authors to `summary.pl --help'.
* manual/summary.awk: Remove file.
* manual/summary.pl: New file. Generate summary.texi, and
check for @standards-related syntax errors.
* manual/argp.texi: Convert header and standards @comments to
@standards.
* manual/arith.texi: Likewise.
* manual/charset.texi: Likewise.
* manual/conf.texi: Likewise.
* manual/creature.texi: Likewise.
* manual/crypt.texi: Likewise.
* manual/ctype.texi: Likewise.
* manual/debug.texi: Likewise.
* manual/errno.texi: Likewise.
* manual/filesys.texi: Likewise.
* manual/getopt.texi: Likewise.
* manual/job.texi: Likewise.
* manual/lang.texi: Likewise.
* manual/llio.texi: Likewise.
* manual/locale.texi: Likewise.
* manual/math.texi: Likewise.
* manual/memory.texi: Likewise.
* manual/message.texi: Likewise.
* manual/pattern.texi: Likewise.
* manual/pipe.texi: Likewise.
* manual/process.texi: Likewise.
* manual/resource.texi: Likewise.
* manual/search.texi: Likewise.
* manual/setjmp.texi: Likewise.
* manual/signal.texi: Likewise.
* manual/socket.texi: Likewise.
* manual/startup.texi: Likewise.
* manual/stdio.texi: Likewise.
* manual/string.texi: Likewise.
* manual/sysinfo.texi: Likewise.
* manual/syslog.texi: Likewise.
* manual/terminal.texi: Likewise.
* manual/threads.texi: Likewise.
* manual/time.texi: Likewise.
* manual/users.texi: Likewise.
As described in BZ#21398 (close as dup of 21393) report current
freopen implementation fails when one tries to freopen STDIN_FILENO,
STDOUT_FILENO, or STDERR_FILENO. Although on bug report the
discussion leads to argue if a close followed by a freopen on the
standard file is a valid operation, the underlying issue is not
really the check for dup3 returned value, but rather calling it
if the returned file descriptor is equal as the input one.
So for a quality of implementation this patch avoid calling dup3
for the aforementioned case. It also adds a dup3 error case check
for the two possible failures, with one being Linux only: EINTR and
EBUSY. The EBUSY issue is better explained on this stackoverflow
thread [1], but in a short it is due the internal Linux
implementation which allows a race condition window for dup2 due
the logic dissociation of file descriptor allocation and actual
VFS 'install' operation. For both outliers failures all allocated
memory is freed and a NULL FILE* is returned.
With this patch the example on BZ#21398 is now actually possible
(I used as the testcase for the bug report). Checked on
x86_64-linux-gnu.
[BZ #21393]
* libio/freopen.c (freopen): Avoid dup already opened file descriptor
and add a check for dup3 failure.
* libio/freopen64.c (freopen64): Likewise.
* libio/tst-freopen.c (do_test): Rename to do_test_basic and use
libsupport.
(do_test_bz21398): New test.
* manual/stdio.texi (freopen): Add documentation of EBUSY failure.
[1] http://stackoverflow.com/questions/23440216/race-condition-when-using-dup2
Texinfo @vindex commands add entries to the Variable and Constant
Macro Index. Similarly, @items in @vtables are automatically indexed.
A number of @tables exist where all @items are @vindexed or all @items
are variables, but not indexed, suggesting an optimization by
converting such @tables to @vtables and dropping the @vindex.
Using a @vtable provides a context for processing @items whereby it
can be known the @items should have header and standards annotations.
This commit converts @tables of such @items to @vtables in order to
establish a framework for automated processing.
A pleasant consequence of these changes is that @items previously
lacking a @vindex are present in the Variable and Constant Macro Index
now. @vindex entries previously detected by summary.awk will still be
detected as @items with appropriate annotations.
The @vtable of the NSS databases is converted to a @table because 1)
those @items are not variables (and will no longer appear in the
Variable and Constant Macro Index) and 2) they do not need header and
standards annotations, so the incorrect context is fixed.
* manual/nss.texi: Change incorrect @vtable to @table.
* manual/arith.texi: Convert @tables of variables to @vtables
and remove unnecessary indexing.
* manual/filesys.texi: Likewise.
* manual/llio.texi: Likewise.
* manual/memory.texi: Likewise.
* manual/process.texi: Likewise.
* manual/resource.texi: Likewise.
* manual/search.texi: Likewise.
* manual/signal.texi: Likewise.
* manual/socket.texi: Likewise.
* manual/stdio.texi: Likewise.
* manual/sysinfo.texi: Likewise.
* manual/syslog.texi: Likewise.
* manual/terminal.texi: Likewise.
* manual/time.texi: Likewise.
* manual/users.texi: Likewise.
* manual/examples/strncat.c: Remove.
This example was misleading, as the code would have undefined
behavior if "hello" was longer than SIZE. Anyway, the manual
shouldn't encourage strncpy+strncat for this sort of thing.
* manual/string.texi (Copying Strings and Arrays): Split into
three sections Copying Strings and Arrays, Concatenating Strings,
and Truncating Strings, as this section was way too long. All
cross-referenced changed. Add advice about string-truncation
functions. Remove misleading strncat example.
If the user has requested automatic buffer creation, getline may create
it and not free things when an error occurs. That means the user is
always responsible for calling free() regardless of the return value.
The current documentation does not explicitly cover this which leaves it
slightly ambiguous to the reader. So clarify things.
URL: https://sourceware.org/bugzilla/show_bug.cgi?id=5666
DJ Delorie
Carlos O'Donell
Florian Weimer
Joseph Myers
Siddhesh Poyarekar
Arjun Shankar
Joseph Myers
Paul Eggert
Paul Pluzhnikov
Jakub Wilk
Alyssa Ross
Girish Joshi
Martin Sebor
Rical Jasan
Adhemerval Zanella
Ondřej Bílka
David Svoboda
Alexandre Oliva
Ville Skytta
Roland McGrath
Allan McRae
Jeff Law
Petr Baudis
Andreas Jaeger