Merge "linker: update non-PIE error message." into main
diff --git a/libc/include/android/api-level.h b/libc/include/android/api-level.h
index 77ec653..1bde3a5 100644
--- a/libc/include/android/api-level.h
+++ b/libc/include/android/api-level.h
@@ -168,7 +168,10 @@
  */
 #define __ANDROID_API_U__ 34
 
-/** Names the "V" API level (35), for comparison against `__ANDROID_API__`. */
+/**
+ * Names the Android 15 (aka "V" or "VanillaIceCream") API level (35),
+ * for comparison against `__ANDROID_API__`.
+ */
 #define __ANDROID_API_V__ 35
 
 /* This file is included in <features.h>, and might be used from .S files. */
diff --git a/libc/include/android/dlext.h b/libc/include/android/dlext.h
index a5061c7..b42e5b2 100644
--- a/libc/include/android/dlext.h
+++ b/libc/include/android/dlext.h
@@ -14,8 +14,7 @@
  * limitations under the License.
  */
 
-#ifndef __ANDROID_DLEXT_H__
-#define __ANDROID_DLEXT_H__
+#pragma once
 
 #include <stdbool.h>
 #include <stddef.h>
@@ -101,7 +100,7 @@
   ANDROID_DLEXT_FORCE_LOAD = 0x40,
 
   // Historically we had two other options for ART.
-  // They were last available in Android P.
+  // They were last available in API level 28.
   // Reuse these bits last!
   // ANDROID_DLEXT_FORCE_FIXED_VADDR = 0x80
   // ANDROID_DLEXT_LOAD_AT_FIXED_ADDRESS = 0x100
@@ -115,7 +114,7 @@
   ANDROID_DLEXT_USE_NAMESPACE = 0x200,
 
   /**
-   * Instructs dlopen to apply `ANDROID_DLEXT_RESERVED_ADDRESS`,
+   * Instructs dlopen() to apply `ANDROID_DLEXT_RESERVED_ADDRESS`,
    * `ANDROID_DLEXT_RESERVED_ADDRESS_HINT`, `ANDROID_DLEXT_WRITE_RELRO` and
    * `ANDROID_DLEXT_USE_RELRO` to any libraries loaded as dependencies of the
    * main library as well.
@@ -151,7 +150,7 @@
 
 struct android_namespace_t;
 
-/** Used to pass Android-specific arguments to `android_dlopen_ext`. */
+/** Used to pass Android-specific arguments to android_dlopen_ext(). */
 typedef struct {
   /** A bitmask of `ANDROID_DLEXT_` enum values. */
   uint64_t flags;
@@ -183,5 +182,3 @@
 __END_DECLS
 
 /** @} */
-
-#endif
diff --git a/libc/include/link.h b/libc/include/link.h
index 33fea49..ee1fc42 100644
--- a/libc/include/link.h
+++ b/libc/include/link.h
@@ -25,8 +25,13 @@
  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  * SUCH DAMAGE.
  */
-#ifndef _LINK_H_
-#define _LINK_H_
+
+#pragma once
+
+/**
+ * @file link.h
+ * @brief Extra dynamic linker functionality (see also <dlfcn.h>).
+ */
 
 #include <stdint.h>
 #include <sys/cdefs.h>
@@ -37,32 +42,80 @@
 __BEGIN_DECLS
 
 #if defined(__LP64__)
+/** Convenience macro to get the appropriate 32-bit or 64-bit <elf.h> type for the caller's bitness. */
 #define ElfW(type) Elf64_ ## type
 #else
+/** Convenience macro to get the appropriate 32-bit or 64-bit <elf.h> type for the caller's bitness. */
 #define ElfW(type) Elf32_ ## type
 #endif
 
+/**
+ * Information passed by dl_iterate_phdr() to the callback.
+ */
 struct dl_phdr_info {
+  /** The address of the shared object. */
   ElfW(Addr) dlpi_addr;
+  /** The name of the shared object. */
   const char* _Nullable dlpi_name;
+  /** Pointer to the shared object's program headers. */
   const ElfW(Phdr)* _Nullable dlpi_phdr;
+  /** Number of program headers pointed to by `dlpi_phdr`. */
   ElfW(Half) dlpi_phnum;
 
-  // These fields were added in Android R.
+  /**
+   * The total number of library load events at the time dl_iterate_phdr() was
+   * called.
+   *
+   * This field is only available since API level 30; you can use the size
+   * passed to the callback to determine whether you have the full struct,
+   * or just the fields up to and including `dlpi_phnum`.
+   */
   unsigned long long dlpi_adds;
+  /**
+   * The total number of library unload events at the time dl_iterate_phdr() was
+   * called.
+   *
+   * This field is only available since API level 30; you can use the size
+   * passed to the callback to determine whether you have the full struct,
+   * or just the fields up to and including `dlpi_phnum`.
+   */
   unsigned long long dlpi_subs;
+  /**
+   * The module ID for TLS relocations in this shared object.
+   *
+   * This field is only available since API level 30; you can use the size
+   * passed to the callback to determine whether you have the full struct,
+   * or just the fields up to and including `dlpi_phnum`.
+   */
   size_t dlpi_tls_modid;
+  /**
+   * The caller's TLS data for this shared object.
+   *
+   * This field is only available since API level 30; you can use the size
+   * passed to the callback to determine whether you have the full struct,
+   * or just the fields up to and including `dlpi_phnum`.
+   */
   void* _Nullable dlpi_tls_data;
 };
 
-int dl_iterate_phdr(int (* _Nonnull __callback)(struct dl_phdr_info* _Nonnull, size_t, void* _Nullable), void* _Nullable __data);
+/**
+ * [dl_iterate_phdr(3)](http://man7.org/linux/man-pages/man3/dl_iterate_phdr.3.html)
+ * calls the given callback once for every loaded shared object. The size
+ * argument to the callback lets you determine whether you have a smaller
+ * `dl_phdr_info` from before API level 30, or the newer full one.
+ * The data argument to the callback is whatever you pass as the data argument
+ * to dl_iterate_phdr().
+ *
+ * Returns the value returned by the final call to the callback.
+ */
+int dl_iterate_phdr(int (* _Nonnull __callback)(struct dl_phdr_info* _Nonnull __info, size_t __size, void* _Nullable __data), void* _Nullable __data);
 
 #ifdef __arm__
 typedef uintptr_t _Unwind_Ptr;
 _Unwind_Ptr dl_unwind_find_exidx(_Unwind_Ptr, int* _Nonnull);
 #endif
 
-/* Used by the dynamic linker to communicate with the debugger. */
+/** Used by the dynamic linker to communicate with the debugger. */
 struct link_map {
   ElfW(Addr) l_addr;
   char* _Nullable l_name;
@@ -71,7 +124,7 @@
   struct link_map* _Nullable l_prev;
 };
 
-/* Used by the dynamic linker to communicate with the debugger. */
+/** Used by the dynamic linker to communicate with the debugger. */
 struct r_debug {
   int32_t r_version;
   struct link_map* _Nullable r_map;
@@ -85,5 +138,3 @@
 };
 
 __END_DECLS
-
-#endif
diff --git a/libc/include/sys/system_properties.h b/libc/include/sys/system_properties.h
index dc869da..ae94db5 100644
--- a/libc/include/sys/system_properties.h
+++ b/libc/include/sys/system_properties.h
@@ -26,8 +26,12 @@
  * SUCH DAMAGE.
  */
 
-#ifndef _INCLUDE_SYS_SYSTEM_PROPERTIES_H
-#define _INCLUDE_SYS_SYSTEM_PROPERTIES_H
+#pragma once
+
+/**
+ * @file system_properties.h
+ * @brief System properties.
+ */
 
 #include <sys/cdefs.h>
 #include <stdbool.h>
@@ -36,39 +40,53 @@
 
 __BEGIN_DECLS
 
+/** An opaque structure representing a system property. */
 typedef struct prop_info prop_info;
 
+/**
+ * The limit on the length of a property value.
+ * (See PROP_NAME_MAX for property names.)
+ */
 #define PROP_VALUE_MAX  92
 
-/*
+/**
  * Sets system property `name` to `value`, creating the system property if it doesn't already exist.
+ *
+ * Returns 0 on success, or -1 on failure.
  */
 int __system_property_set(const char* _Nonnull __name, const char* _Nonnull __value);
 
-/*
+/**
  * Returns a `prop_info` corresponding system property `name`, or nullptr if it doesn't exist.
- * Use __system_property_read_callback to query the current value.
+ * Use __system_property_read_callback() to query the current value.
  *
- * Property lookup is expensive, so it can be useful to cache the result of this function.
+ * Property lookup is expensive, so it can be useful to cache the result of this
+ * function rather than using __system_property_get().
  */
 const prop_info* _Nullable __system_property_find(const char* _Nonnull __name);
 
-/*
- * Calls `callback` with a consistent trio of name, value, and serial number for property `pi`.
+/**
+ * Calls `callback` with a consistent trio of name, value, and serial number
+ * for property `pi`.
+ *
+ * Available since API level 26.
  */
 void __system_property_read_callback(const prop_info* _Nonnull __pi,
     void (* _Nonnull __callback)(void* _Nullable __cookie, const char* _Nonnull __name, const char* _Nonnull __value, uint32_t __serial),
     void* _Nullable __cookie) __INTRODUCED_IN(26);
 
-/*
+/**
  * Passes a `prop_info` for each system property to the provided
- * callback.  Use __system_property_read_callback() to read the value.
+ * callback. Use __system_property_read_callback() to read the value of
+ * any of the properties.
  *
  * This method is for inspecting and debugging the property system, and not generally useful.
+ *
+ * Returns 0 on success, or -1 on failure.
  */
 int __system_property_foreach(void (* _Nonnull __callback)(const prop_info* _Nonnull __pi, void* _Nullable __cookie), void* _Nullable __cookie);
 
-/*
+/**
  * Waits for the specific system property identified by `pi` to be updated
  * past `old_serial`. Waits no longer than `relative_timeout`, or forever
  * if `relative_timeout` is null.
@@ -79,20 +97,24 @@
  *
  * Returns true and updates `*new_serial_ptr` on success, or false if the call
  * timed out.
+ *
+ * Available since API level 26.
  */
 struct timespec;
 bool __system_property_wait(const prop_info* _Nullable __pi, uint32_t __old_serial, uint32_t* _Nonnull __new_serial_ptr, const struct timespec* _Nullable __relative_timeout)
     __INTRODUCED_IN(26);
 
-/* Deprecated. In Android O and above, there's no limit on property name length. */
+/**
+ * Deprecated: there's no limit on the length of a property name since
+ * API level 26, though the limit on property values (PROP_VALUE_MAX) remains.
+ */
 #define PROP_NAME_MAX   32
-/* Deprecated. Use __system_property_read_callback instead. */
+
+/** Deprecated. Use __system_property_read_callback() instead. */
 int __system_property_read(const prop_info* _Nonnull __pi, char* _Nullable __name, char* _Nonnull __value);
-/* Deprecated. Use __system_property_read_callback instead. */
+/** Deprecated. Use __system_property_read_callback() instead. */
 int __system_property_get(const char* _Nonnull __name, char* _Nonnull __value);
-/* Deprecated. Use __system_property_foreach instead. */
+/** Deprecated. Use __system_property_foreach() instead. */
 const prop_info* _Nullable __system_property_find_nth(unsigned __n);
 
 __END_DECLS
-
-#endif
diff --git a/linker/linker_phdr.cpp b/linker/linker_phdr.cpp
index fa712a1..b9229ca 100644
--- a/linker/linker_phdr.cpp
+++ b/linker/linker_phdr.cpp
@@ -298,7 +298,6 @@
   }
 
   if (header_.e_shentsize != sizeof(ElfW(Shdr))) {
-    // Fail if app is targeting Android O or above
     if (get_application_target_sdk_version() >= 26) {
       DL_ERR_AND_LOG("\"%s\" has unsupported e_shentsize: 0x%x (expected 0x%zx)",
                      name_.c_str(), header_.e_shentsize, sizeof(ElfW(Shdr)));
@@ -312,12 +311,10 @@
   }
 
   if (header_.e_shstrndx == 0) {
-    // Fail if app is targeting Android O or above
     if (get_application_target_sdk_version() >= 26) {
       DL_ERR_AND_LOG("\"%s\" has invalid e_shstrndx", name_.c_str());
       return false;
     }
-
     DL_WARN_documented_change(26,
                               "invalid-elf-header_section-headers-enforced-for-api-level-26",
                               "\"%s\" has invalid e_shstrndx", name_.c_str());