Nullability check for stat module
Bugs: b/245972273
Test: None
Change-Id: I8611c7d7c22e2fb6b0cec4b5101dbcb3174ae706
diff --git a/libc/include/sys/stat.h b/libc/include/sys/stat.h
index 623631e..53e3e26 100644
--- a/libc/include/sys/stat.h
+++ b/libc/include/sys/stat.h
@@ -136,20 +136,20 @@
#define S_TYPEISSHM(__sb) 0
#define S_TYPEISTMO(__sb) 0
-int chmod(const char* __path, mode_t __mode);
+int chmod(const char* _Nonnull __path, mode_t __mode);
int fchmod(int __fd, mode_t __mode);
-int mkdir(const char* __path, mode_t __mode);
+int mkdir(const char* _Nonnull __path, mode_t __mode);
-int fstat(int __fd, struct stat* __buf);
-int fstat64(int __fd, struct stat64* __buf) __RENAME_STAT64(fstat, 3, 21);
-int fstatat(int __dir_fd, const char* __path, struct stat* __buf, int __flags);
-int fstatat64(int __dir_fd, const char* __path, struct stat64* __buf, int __flags) __RENAME_STAT64(fstatat, 3, 21);
-int lstat(const char* __path, struct stat* __buf);
-int lstat64(const char* __path, struct stat64* __buf) __RENAME_STAT64(lstat, 3, 21);
-int stat(const char* __path, struct stat* __buf);
-int stat64(const char* __path, struct stat64* __buf) __RENAME_STAT64(stat, 3, 21);
+int fstat(int __fd, struct stat* _Nonnull __buf);
+int fstat64(int __fd, struct stat64* _Nonnull __buf) __RENAME_STAT64(fstat, 3, 21);
+int fstatat(int __dir_fd, const char* _Nonnull __path, struct stat* _Nonnull __buf, int __flags);
+int fstatat64(int __dir_fd, const char* _Nonnull __path, struct stat64* _Nonnull __buf, int __flags) __RENAME_STAT64(fstatat, 3, 21);
+int lstat(const char* _Nonnull __path, struct stat* _Nonnull __buf);
+int lstat64(const char* _Nonnull __path, struct stat64* _Nonnull __buf) __RENAME_STAT64(lstat, 3, 21);
+int stat(const char* _Nonnull __path, struct stat* _Nonnull __buf);
+int stat64(const char* _Nonnull __path, struct stat64* _Nonnull __buf) __RENAME_STAT64(stat, 3, 21);
-int mknod(const char* __path, mode_t __mode, dev_t __dev);
+int mknod(const char* _Nonnull __path, mode_t __mode, dev_t __dev);
mode_t umask(mode_t __mask);
#if defined(__BIONIC_INCLUDE_FORTIFY_HEADERS)
@@ -157,21 +157,58 @@
#endif
#if __ANDROID_API__ >= 21
-int mkfifo(const char* __path, mode_t __mode) __INTRODUCED_IN(21);
+int mkfifo(const char* _Nonnull __path, mode_t __mode) __INTRODUCED_IN(21);
#else
// Implemented as a static inline before 21.
#endif
-int mkfifoat(int __dir_fd, const char* __path, mode_t __mode) __INTRODUCED_IN(23);
+int mkfifoat(int __dir_fd, const char* _Nonnull __path, mode_t __mode) __INTRODUCED_IN(23);
-int fchmodat(int __dir_fd, const char* __path, mode_t __mode, int __flags);
-int mkdirat(int __dir_fd, const char* __path, mode_t __mode);
-int mknodat(int __dir_fd, const char* __path, mode_t __mode, dev_t __dev) __INTRODUCED_IN(21);
+int fchmodat(int __dir_fd, const char* _Nonnull __path, mode_t __mode, int __flags);
+int mkdirat(int __dir_fd, const char* _Nonnull __path, mode_t __mode);
+int mknodat(int __dir_fd, const char* _Nonnull __path, mode_t __mode, dev_t __dev) __INTRODUCED_IN(21);
+/**
+ * Used in the tv_nsec field of an argument to utimensat()/futimens()
+ * to set that time to the current time.
+ */
#define UTIME_NOW ((1L << 30) - 1L)
+
+/**
+ * Used in the tv_nsec field of an argument to utimensat()/futimens()
+ * to _not_ set that time.
+ */
#define UTIME_OMIT ((1L << 30) - 2L)
-int utimensat(int __dir_fd, const char* __path, const struct timespec __times[2], int __flags);
-int futimens(int __dir_fd, const struct timespec __times[2]) __INTRODUCED_IN(19);
+
+/**
+ * [utimensat(2)](https://man7.org/linux/man-pages/man2/utimensat.2.html) sets
+ * file timestamps.
+ *
+ * Note: Linux supports `__path` being NULL (in which case `__dir_fd` need not
+ * be a directory), allowing futimens() to be implemented with utimensat().
+ * For normal use of utimensat(), though, `__path` should be non-null.
+ *
+ * `__times[0]` is the access time (atime), and `__times[1]` the last modification time (mtime).
+ * If `__times` is NULL, both times are set to the current time.
+ * See also UTIME_NOW and UTIME_OMIT.
+ *
+ * Returns 0 on success and returns -1 and sets `errno` on failure.
+ */
+int utimensat(int __dir_fd, const char* __BIONIC_COMPLICATED_NULLNESS __path, const struct timespec __times[_Nullable 2], int __flags);
+
+/**
+ * [futimens(2)](https://man7.org/linux/man-pages/man2/utimensat.2.html) sets
+ * the given file descriptor's timestamp.
+ *
+ * `__times[0]` is the access time (atime), and `__times[1]` the last modification time (mtime).
+ * If `__times` is NULL, both times are set to the current time.
+ * See also UTIME_NOW and UTIME_OMIT.
+ *
+ * Returns 0 on success and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 19.
+ */
+int futimens(int __fd, const struct timespec __times[_Nullable 2]) __INTRODUCED_IN(19);
#if defined(__USE_GNU)
/**
@@ -179,8 +216,10 @@
* extended file status information.
*
* Returns 0 on success and returns -1 and sets `errno` on failure.
+ *
+ * Available since API level 30.
*/
-int statx(int __dir_fd, const char* __path, int __flags, unsigned __mask, struct statx* __buf) __INTRODUCED_IN(30);
+int statx(int __dir_fd, const char* _Nonnull __path, int __flags, unsigned __mask, struct statx* _Nonnull __buf) __INTRODUCED_IN(30);
#endif
__END_DECLS