Improve the _FILE_OFFSET_BITS docs and link to them.
We're still seeing lots of confusion. People do seem to look as far as
the headers, but stop there. So let's try a bit harder to point them in
the right direction.
Also explicitly state that removing _FILE_OFFSET_BITS=64 is the
behavior-preserving fix for compilation problems when upgrading to NDK
r15 or later.
Bug: N/A
Test: N/A
Change-Id: I2d5c65b2fb5cccb9977901e51fea1ad2ccc0fd95
diff --git a/libc/include/sys/cdefs.h b/libc/include/sys/cdefs.h
index 833ced0..3cf6723 100644
--- a/libc/include/sys/cdefs.h
+++ b/libc/include/sys/cdefs.h
@@ -205,25 +205,28 @@
* In our header files we test against __USE_BSD and __USE_GNU.
*/
#if defined(_GNU_SOURCE)
-# define __USE_BSD 1
-# define __USE_GNU 1
+# define __USE_BSD 1
+# define __USE_GNU 1
#endif
#if defined(_BSD_SOURCE)
-# define __USE_BSD 1
+# define __USE_BSD 1
#endif
-/* _FILE_OFFSET_BITS 64 support. */
+/*
+ * _FILE_OFFSET_BITS 64 support.
+ * See https://android.googlesource.com/platform/bionic/+/master/docs/32-bit-abi.md
+ */
#if !defined(__LP64__) && defined(_FILE_OFFSET_BITS) && _FILE_OFFSET_BITS == 64
-#define __USE_FILE_OFFSET64 1
+# define __USE_FILE_OFFSET64 1
/*
* Note that __RENAME_IF_FILE_OFFSET64 is only valid if the off_t and off64_t
* functions were both added at the same API level because if you use this,
* you only have one declaration to attach __INTRODUCED_IN to.
*/
-#define __RENAME_IF_FILE_OFFSET64(func) __RENAME(func)
+# define __RENAME_IF_FILE_OFFSET64(func) __RENAME(func)
#else
-#define __RENAME_IF_FILE_OFFSET64(func)
+# define __RENAME_IF_FILE_OFFSET64(func)
#endif
/*
diff --git a/libc/include/sys/mman.h b/libc/include/sys/mman.h
index 028b024..5a7e3c0 100644
--- a/libc/include/sys/mman.h
+++ b/libc/include/sys/mman.h
@@ -44,8 +44,9 @@
#define MREMAP_MAYMOVE 1
#define MREMAP_FIXED 2
-#if defined(__USE_FILE_OFFSET64)
/*
+ * See https://android.googlesource.com/platform/bionic/+/master/docs/32-bit-abi.md
+ *
* mmap64 wasn't really around until L, but we added an inline for it since it
* allows a lot more code to compile with _FILE_OFFSET_BITS=64.
*
@@ -54,17 +55,18 @@
* mmap64 to every translation unit that includes this header. Instead, just
* preserve the old behavior for GCC and emit a useful diagnostic.
*/
+#if defined(__USE_FILE_OFFSET64)
void* mmap(void* __addr, size_t __size, int __prot, int __flags, int __fd, off_t __offset)
-#if !defined(__clang__) && __ANDROID_API__ < __ANDROID_API_L__
- __attribute__((error("mmap is not available with _FILE_OFFSET_BITS=64 when using GCC until "
- "android-21. Either raise your minSdkVersion, disable "
- "_FILE_OFFSET_BITS=64, or switch to Clang.")));
-#else
+# if !defined(__clang__) && __ANDROID_API__ < __ANDROID_API_L__
+ __attribute__((error("mmap is not available with _FILE_OFFSET_BITS=64 when using GCC until "
+ "android-21. Either raise your minSdkVersion, disable "
+ "_FILE_OFFSET_BITS=64, or switch to Clang.")));
+# else
__RENAME(mmap64);
-#endif /* defined(__clang__) */
+# endif
#else
void* mmap(void* __addr, size_t __size, int __prot, int __flags, int __fd, off_t __offset);
-#endif /* defined(__USE_FILE_OFFSET64) */
+#endif
#if __ANDROID_API__ >= __ANDROID_API_L__
void* mmap64(void* __addr, size_t __size, int __prot, int __flags, int __fd, off64_t __offset) __INTRODUCED_IN(21);
diff --git a/libc/include/sys/sendfile.h b/libc/include/sys/sendfile.h
index ecdb76c..97432c0 100644
--- a/libc/include/sys/sendfile.h
+++ b/libc/include/sys/sendfile.h
@@ -34,6 +34,7 @@
__BEGIN_DECLS
+/* See https://android.googlesource.com/platform/bionic/+/master/docs/32-bit-abi.md */
#if defined(__USE_FILE_OFFSET64)
ssize_t sendfile(int __out_fd, int __in_fd, off_t* __offset, size_t __count) __RENAME(sendfile64) __INTRODUCED_IN(21);
#else
diff --git a/libc/include/sys/types.h b/libc/include/sys/types.h
index 26ad6a5..f07c8fd 100644
--- a/libc/include/sys/types.h
+++ b/libc/include/sys/types.h
@@ -95,12 +95,13 @@
typedef __kernel_time_t __time_t;
typedef __time_t time_t;
+/* This historical accident means that we had a 32-bit off_t on 32-bit architectures. */
+/* See https://android.googlesource.com/platform/bionic/+/master/docs/32-bit-abi.md */
#if defined(__USE_FILE_OFFSET64) || defined(__LP64__)
typedef int64_t off_t;
typedef off_t loff_t;
typedef loff_t off64_t;
#else
-/* This historical accident means that we had a 32-bit off_t on 32-bit architectures. */
typedef __kernel_off_t off_t;
typedef __kernel_loff_t loff_t;
typedef loff_t off64_t;