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>
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.
This is a thorough revision of all the material relating to the
functions time, stime, gettimeofday, settimeofday, clock_gettime,
clock_getres, clock_settime, and difftime, spilling over into the
discussion of time-related data types (which now get their own
section) and touching the adjtime family as well (which deserves its
own thorough revision, but I'd have to do a bunch of research first).
Substantive changes are:
* Document clock_gettime, clock_getres, and clock_settime. (Only
CLOCK_REALTIME and CLOCK_MONOTONIC are documented; the others are
either a bit too Linux-specific, or have more to do with measuring
CPU/processor time. That section _also_ deserves its own thorough
revision but again I'd have to do a bunch of research first.)
* Present gettimeofday, settimeofday, and struct timeval as obsolete
relative to clock_*.
* Remove the documentation of struct timezone. Matching POSIX,
say that the type of the second argument to gettimeofday and
settimeofday is [const] void *.
* Clarify ISO C and POSIX's requirements on time_t. Clarify the
circumstances under which difftime is equivalent to simple
subtraction.
* Consolidate documentation of most of the time-related data types
into a new section "Time Types," right after "Time Basics." (The
exceptions are struct tm, which stays in "Broken-down Time," and
struct times, which stays in "Processor And CPU Time."
* The "Elapsed Time" section is now called "Calculating Elapsed Time"
and includes only difftime and the discussion of how to compute
timeval differences by hand.
* Fold the "Simple Calendar Time," "High Resolution Calendar," and
"High Accuracy Clock" sections together into two new sections titled
"Getting the Time" and "Setting and Adjusting the Time."
No 32-bit system call wrapper is added because the interface
is problematic because it cannot deal with 64-bit inode numbers
and 64-bit directory hashes.
A future commit will deprecate the undocumented getdirentries
and getdirentries64 functions.
Reviewed-by: Carlos O'Donell <carlos@redhat.com>
@var is intended for placeholders (such as function parameters).
Actual variables need to use @code because @var causes upper-case
output, resulting in a different C identifier.
The implementation falls back to renameat if renameat2 is not available
in the kernel (or in the kernel headers) and the flags argument is zero.
Without kernel support, a non-zero argument returns EINVAL, not ENOSYS.
This mirrors what the kernel does for invalid renameat2 flags.
This is a minor rewording to clarify the behaviour of
get_current_dir_name. Additionally, the @vindex is moved above the
@deftypefun so that following links give a better result with regard
to context.
[BZ #6889]
* manual/filesys.texi (get_current_dir_name): Clarify
behaviour.
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.
This commit handles exceptional cases of invalid syntax for the
@standards conversion script.
* manual/crypt.texi: Move a comment out of an @*x list.
* manual/filesys.texi: Refactor some comments, one of which
looks like a standard. Fix incorrectly separated standards.
* manual/locale.texi: Invert an annotation.
* manual/resource.texi: Fix incorrectly separated standards.
* manual/time.texi: Refactor a @vtable that obscures an
annotation.
* manual/users.texi: Refactor multiple headers to occupy a
single @comment.
They only modify the state in the dirstream argument, and we
generally do not treat this as a reason to mark a function as
not thread-safe. For an example, see random_r, which is marked
as thread-safe even though the random state is not protected
by a lock.
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.
The argument order for posix_fallocate64 in the manual
was wrong, it was listed as [fd, len, offset] when it
should have been [fd, offset, len].
Verified io/fcntl.h has the right argument order, and it
does. Verified generated PDF.
In the posix_fallocate description in the manual we list various
drawbacks with the emulation, including the fact that a file opened
with O_APPEND fails with EBADF. Similarly a file opened with O_WRONLY
fails with EBADF. We must be able to emulate a compare-and-swap via
pread/compare/pwrite in order to make the emulation as safe as possible.
It is not acceptable to ignore the read failure because it could result
in significant data loss across all of the blocks. There is no other way
to make this work without a true atomic CAS and SIGBUS handler (which
is looking more attractive as a way to remove the race condition).
This patch adds O_WRONLY to the manual as another bullet to clarify the
limits of the emulation.
Manual looks good in PDF.
Handle signed integer overflow correctly. Detect and reject O_APPEND.
Document drawbacks of emulation.
This does not completely address bug 15661, but improves the situation
somewhat.
The four functions {alpha,version}sort{,64} take parameters of type
const struct dirent{,64} **, not const void *.
Signed-off-by: Rasmus Villemoes <rv@rasmusvillemoes.dk>
This is a minimal patch to remove _BSD_SOURCE and _SVID_SOURCE from
the documented user API, making them into aliases for _DEFAULT_SOURCE
with a #warning given, but keeping most of the features.h logic using
those macros and all the exising __USE_* conditionals, on the basis
that all the consequent cleanups will go in followup patches.
Tested x86_64.
* include/features.h: Update comment documenting feature test
macros.
[_BSD_SOURCE || _SVID_SOURCE]: Give #warning. Define
_DEFAULT_SOURCE.
* manual/creature.texi (_BSD_SOURCE): Remove documentation.
(_SVID_SOURCE): Likewise.
(_DEFAULT_SOURCE): Update description of default features.
(Feature Test Macros): Don't mention _SVID_SOURCE in conjunction
with _GNU_SOURCE.
* manual/filesys.texi (__ftw_func_t): Do not refer to _BSD_SOURCE.
(S_ISVTX): Likewise.
* manual/math.texi (Mathematical Constants): Likewise.
* manual/signal.texi (Interrupted Primitives): Likewise.
* manual/startup.texi (putenv): Do not refer to _SVID_SOURCE.
* math/test-matherr.c (_SVID_SOURCE): Do not define.
* sysvipc/sys/ipc.h [__USE_SVID && !__USE_XOPEN && __GNUC__ >= 2]:
Don't refer to _SVID_SOURCE in warning text.
* manual/filesys.texi (Symbolic Links): Fix description of
canonicalize_file_name based on patch by Oskar Liljeblad
<oskar@osk.mine.nu>.
2005-12-31 Andreas Jaeger <aj@suse.de>
[BZ #1395]
* manual/filesys.texi (Symbolic Links): Fix description of
canonicalize_file_name based on patch by Oskar Liljeblad
<oskar@osk.mine.nu>.
2003-11-07 Jakub Jelinek <jakub@redhat.com>
* io/ftw.c (NFTW_OLD_NAME, NFTW_NEW_NAME): Define.
(ftw_dir, ftw_startup): Add __attribute ((noinline)).
(NFTW_OLD_NAME, NFTW_NEW_NAME): New functions.
(NFTW_NAME): Only define if !_LIBC, add versioned_symbol
and compat_symbol.
* io/ftw64.c (NFTW_OLD_NAME, NFTW_NEW_NAME): Define.
* io/Versions (libc): Export nftw@@GLIBC_2.3.3
and nftw64@@GLIBC_2.3.3.
* io/ftw.h (FTW_ACTIONRETVAL): New flag.
(FTW_CONTINUE, FTW_STOP, FTW_SKIP_SUBTREE, FTW_SKIP_SIBLINGS): New.
* io/ftw.c (ftw_dir): Add old_dir argument.
Clear result if it was FTW_SKIP_SIBLINGS after processing all
dir entries. Change cwd back if old_dir != NULL.
(process_entry): Adjust caller. Don't change cwd back here.
Change FTW_SKIP_SUBTREE result to 0.
(ftw_startup): Adjust ftw_dir caller.
Clear result if it was FTW_SKIP_SUBTREE or FTW_SKIP_SIBLINGS.
* io/ftwtest.c (skip_subtree, skip_siblings): New variables.
(options, main): Add --skip-subtree and --skip-siblings options.
(cb): Use return FTW_CONTINUE instead of return 0.
Handle --skip-subtree and --skip-siblings.
* io/ftwtest-sh: Add tests for FTW_ACTIONRETVAL.
* manual/filesys.texi: Document FTW_ACTIONRETVAL.
description to be clearer and to say that *RESULT is set to ENTRY.
2002-10-30 Jakub Jelinek <jakub@redhat.com>
* posix/regexec.c (build_trtable): Alloca or malloc dests_node and
dests_ch arrays together. Alloca or malloc dest_states,
dest_states_word and dest_states_nl arrays together. Free memory on
error exit.
2002-10-29 Daniel Jacobowitz <drow@mvista.com>
* crypt/crypt_util.c (__init_des_r): Initialize current_salt
and current_saltbits.
2002-11-02 Roland McGrath <roland@redhat.com>
