diff --git a/libc/include/sys/_system_properties.h b/libc/include/sys/_system_properties.h
index ffa6d2e..fa98d11 100644
--- a/libc/include/sys/_system_properties.h
+++ b/libc/include/sys/_system_properties.h
@@ -30,6 +30,7 @@
 #define _INCLUDE_SYS__SYSTEM_PROPERTIES_H
 
 #include <sys/cdefs.h>
+#include <stdint.h>
 
 #ifndef _REALLY_INCLUDE_SYS__SYSTEM_PROPERTIES_H_
 #error you should #include <sys/system_properties.h> instead
@@ -91,7 +92,7 @@
 **
 ** Returns the serial number on success, -1 on error.
 */
-unsigned int __system_property_area_serial();
+uint32_t __system_property_area_serial();
 
 /* Add a new system property.  Can only be done by a single
 ** process that has write access to the property area, and
@@ -118,12 +119,22 @@
 **
 ** Returns the serial number on success, -1 on error.
 */
-unsigned int __system_property_serial(const prop_info *pi);
+uint32_t __system_property_serial(const prop_info* pi);
 
-/* Wait for any system property to be updated.  Caller must pass
-** in 0 the first time, and the previous return value on each
-** successive call. */
-unsigned int __system_property_wait_any(unsigned int serial);
+/*
+ * Waits for any system property to be updated past `old_serial`.
+ * If you don't know the current global serial number, use 0.
+ * Returns the new global serial number.
+ */
+uint32_t __system_property_wait_any(uint32_t old_serial);
+
+/*
+ * Waits for the specific system property identified by `pi` to be updated past `old_serial`.
+ * If you don't know the current serial, use 0.
+ * Returns the serial number for `pi` that caused the wake.
+ */
+uint32_t __system_property_wait(const prop_info* pi, uint32_t old_serial)
+    __INTRODUCED_IN_FUTURE;
 
 /* Initialize the system properties area in read only mode.
  * Should be done by all processes that need to read system
diff --git a/libc/include/sys/system_properties.h b/libc/include/sys/system_properties.h
index d80b2fe..fb90251 100644
--- a/libc/include/sys/system_properties.h
+++ b/libc/include/sys/system_properties.h
@@ -31,77 +31,52 @@
 
 #include <sys/cdefs.h>
 #include <stddef.h>
+#include <stdint.h>
 
 __BEGIN_DECLS
 
 typedef struct prop_info prop_info;
 
-#define PROP_NAME_MAX   32
 #define PROP_VALUE_MAX  92
 
-/* Look up a system property by name, copying its value and a
-** \0 terminator to the provided pointer.  The total bytes
-** copied will be no greater than PROP_VALUE_MAX.  Returns
-** the string length of the value.  A property that is not
-** defined is identical to a property with a length 0 value.
-*/
-int __system_property_get(const char *name, char *value);
-
-/* Set a system property by name.
-**/
+/*
+ * Sets system property `key` to `value`, creating the system property if it doesn't already exist.
+ */
 int __system_property_set(const char* key, const char* value) __INTRODUCED_IN(12);
 
-/* Return a pointer to the system property named name, if it
-** exists, or NULL if there is no such property.  Use 
-** __system_property_read() to obtain the string value from
-** the returned prop_info pointer.
-**
-** It is safe to cache the prop_info pointer to avoid future
-** lookups.  These returned pointers will remain valid for
-** the lifetime of the system.
-*/
-const prop_info *__system_property_find(const char *name);
+/*
+ * 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.
+ *
+ * Property lookup is expensive, so it can be useful to cache the result of this function.
+ */
+const prop_info* __system_property_find(const char* name);
 
-/* Read the value of a system property.  Returns the length
-** of the value.  Copies the value and \0 terminator into
-** the provided value pointer.  Total length (including
-** terminator) will be no greater that PROP_VALUE_MAX for
-** __system_property_read.
-**
-** If name is nonzero, up to PROP_NAME_MAX bytes will be
-** copied into the provided name pointer.  The name will
-** be \0 terminated.
-*/
-int __system_property_read(const prop_info *pi, char *name, char *value);
+/*
+ * Calls `callback` with a consistent trio of name, value, and serial number for property `pi`.
+ */
 void __system_property_read_callback(const prop_info *pi,
-                                     void (*)(void* cookie, const char *name, const char *value),
-                                     void* cookie) __INTRODUCED_IN_FUTURE;
+    void (*callback)(void* cookie, const char *name, const char *value, uint32_t serial),
+    void* cookie) __INTRODUCED_IN_FUTURE;
 
-/* Return a prop_info for the nth system property, or NULL if 
-** there is no nth property.  Use __system_property_read() to
-** read the value of this property.
-**
-** Please do not call this method.  It only exists to provide
-** backwards compatibility to NDK apps.  Its implementation
-** is inefficient and order of results may change from call
-** to call.
-*/ 
-const prop_info *__system_property_find_nth(unsigned n)
-  __REMOVED_IN(26);
-
-/* Pass a prop_info for each system property to the provided
-** callback.  Use __system_property_read() to read the value
-** of this property.
-**
-** This method is for inspecting and debugging the property
-** system.  Please use __system_property_find() instead.
-**
-** Order of results may change from call to call.  This is
-** not a bug.
-*/
+/*
+ * Passes a `prop_info` for each system property to the provided
+ * callback.  Use __system_property_read_callback() to read the value.
+ *
+ * This method is for inspecting and debugging the property system, and not generally useful.
+ */
 int __system_property_foreach(void (*propfn)(const prop_info* pi, void* cookie), void* cookie)
   __INTRODUCED_IN(19);
 
+/* Deprecated. In Android O and above, there's no limit on property name length. */
+#define PROP_NAME_MAX   32
+/* Deprecated. Use __system_property_read_callback instead. */
+int __system_property_read(const prop_info *pi, char *name, char *value);
+/* Deprecated. Use __system_property_read_callback instead. */
+int __system_property_get(const char *name, char *value);
+/* Deprecated. Use __system_property_foreach instead. Aborts in Android O and above. */
+const prop_info *__system_property_find_nth(unsigned n) __REMOVED_IN(26);
+
 __END_DECLS
 
 #endif