This syscall is available since Linux 3.15 and also implemented in glibc from version 2.28. It is commonly used in filesystem or security contexts. Constants RENAME_NOREPLACE, RENAME_EXCHANGE, RENAME_WHITEOUT are guarded by _GNU_SOURCE as with glibc.
these badly pollute the namespace with macros whenever _GNU_SOURCE is defined, which is always the case with g++, and especially tends to interfere with C++ constructs. as our implementation of these was macro-only, their removal cannot affect any existing binaries. at the source level, portable software should be prepared for them not to exist. for now, they are left in place with explicit _LARGEFILE64_SOURCE. this provides an easy temporary path for integrators/distributions to get packages building again right away if they break while working on a proper, upstreamable fix. the intent is that this be a very short-term measure and that the macros be removed entirely in the next release cycle.
This should be safer for casting and more compatible with existing code bases that wrongly assume it must be defined as a pointer.
C11 removed the requirement that FILE be a complete type, which was deemed erroneous, as part of the changes introduced by N1439 regarding completeness of types (see footnote 6 for specific mention of FILE). however the current version of POSIX is still based on C99 and incorporates the old requirement that FILE be a complete type. expose an arbitrary, useless complete type definition because the actual object used to represent FILE streams cannot be public/ABI. thanks to commit 13d1afa46f8098df290008c681816c9eb89ffbdb, we now have a framework for suppressing the public complete-type definition of FILE when stdio.h is included internally, so that a different internal definition can be provided. this is perfectly well-defined, since the same struct tag can refer to different types in different translation units. it would be a problem if the implementation were accessing the application's FILE objects or vice versa, but either would be undefined behavior.
add a member of appropriate type to the fpos_t union so that accesses are well-defined. use long long instead of off_t since off_t is not always exposed in stdio.h and there's no namespace-clean alias for it. access is still performed using pointer casts rather than by naming the union member as a matter of style; to the extent possible, the naming of fields in opaque types defined in the public headers is not treated as an API contract with the implementation. access via the pointer cast is valid as long as the union has a member of matching type.
stdio types use the struct tag names from glibc libio to match C++ ABI.
notes added by maintainer: this function is a GNU extension. it was chosen over the similar BSD function funopen because the latter depends on fpos_t being an arithmetic type as part of its public API, conflicting with our definition of fpos_t and with the intent that it be an opaque type. it was accepted for inclusion because, despite not being widely used, it is usually very difficult to extricate software using it from the dependency on it. calling pattern for the read and write callbacks is not likely to match glibc or other implementations, but should work with any reasonable callbacks. in particular the read function is never called without at least one byte being needed to satisfy its caller, so that spurious blocking is not introduced. contracts for what callbacks called from inside libc/stdio can do are always complicated, and at some point still need to be specified explicitly. at the very least, the callbacks must return or block indefinitely (they cannot perform nonlocal exits) and they should not make calls to stdio using their own FILE as an argument.
unfortunately this eliminates the ability of the compiler to diagnose some dangerous/incorrect usage, but POSIX requires (as an extension to the C language, i.e. CX shaded) that NULL have type void *. plain C allows it to be defined as any null pointer constant. the definition 0L is preserved for C++ rather than reverting to plain 0 to avoid dangerous behavior in non-conforming programs which use NULL as a variadic sentinel. (it's impossible to use (void *)0 for C++ since C++ lacks the proper implicit pointer conversions, and other popular alternatives like the GCC __null extension seem non-conforming to the standard's requirements.)
the arch-specific bits/alltypes.h.sh has been replaced with a generic alltypes.h.in and minimal arch-specific bits/alltypes.h.in. this commit is intended to have no functional changes except: - exposing additional symbols that POSIX allows but does not require - changing the C++ name mangling for some types - fixing the signedness of blksize_t on powerpc (POSIX requires signed) - fixing the limit macros for sig_atomic_t on x86_64 - making dev_t an unsigned type (ABI matching goal, and more logical) in addition, some types that were wrongly defined with long on 32-bit archs were changed to int, and vice versa; this change is non-functional except for the possibility of making pointer types mismatch, and only affects programs that were using them incorrectly, and only at build-time, not runtime. the following changes were made in the interest of moving non-arch-specific types out of the alltypes system and into the headers they're associated with, and also will tend to improve application compatibility: - netdb.h now includes netinet/in.h (for socklen_t and uint32_t) - netinet/in.h now includes sys/socket.h and inttypes.h - sys/resource.h now includes sys/time.h (for struct timeval) - sys/wait.h now includes signal.h (for siginfo_t) - langinfo.h now includes nl_types.h (for nl_item) for the types in stdint.h: - types which are of no interest to other headers were moved out of the alltypes system. - fast types for 8- and 64-bit are hard-coded (at least for now); only the 16- and 32-bit ones have reason to vary by arch. and the following types have been changed for C++ ABI purposes; - mbstate_t now has a struct tag, __mbstate_t - FILE's struct tag has been changed to _IO_FILE - DIR's struct tag has been changed to __dirstream - locale_t's struct tag has been changed to __locale_struct - pthread_t is defined as unsigned long in C++ mode only - fpos_t now has a struct tag, _G_fpos64_t - fsid_t's struct tag has been changed to __fsid_t - idtype_t has been made an enum type (also required by POSIX) - nl_catd has been changed from long to void * - siginfo_t's struct tag has been removed - sigset_t's has been given a struct tag, __sigset_t - stack_t has been given a struct tag, sigaltstack - suseconds_t has been changed to long on 32-bit archs - [u]intptr_t have been changed from long to int rank on 32-bit archs - dev_t has been made unsigned summary of tests that have been performed against these changes: - nsz's libc-test (diff -u before and after) - C++ ABI check symbol dump (diff -u before, after, glibc) - grepped for __NEED, made sure types needed are still in alltypes - built gcc 3.4.6
POSIX is not clear on whether it includes the termination, but ISO C requires that it does. the whole concept of this macro is rather useless, but it's better to be correct anyway.