feat(times): times (L2 XSI) + CLK_TCK sysconf

2026-09-05 23:17:25 -04:00
parent 3bf875030a
commit fefd17241f
3 changed files with 318 additions and 0 deletions
@@ -0,0 +1,72 @@
+#ifndef VLIBC_SYS_TIMES_H
+#define VLIBC_SYS_TIMES_H
+
+/*
+ * vlibc — <sys/times.h>.
+ *
+ * Process CPU-time accounting in clock ticks. times() and struct tms are
+ * XSI [CX] in POSIX.1-2008 (glibc gates them behind _XOPEN_SOURCE, not
+ * _POSIX_C_SOURCE), so the whole surface sits at level 2 — nothing here is
+ * POSIX.1-2008 base:
+ *
+ *   Level 2 (muslmimic): times, struct tms.
+ *
+ * clock_t is the scalar tick type owned by <sys/types.h> (typedef long
+ * clock_t; <time.h> pulls it from the same place for clock()); this header
+ * includes that one rather than re-typedefing clock_t. The unit of every
+ * times() figure is the tick: CLK_TCK per second, the fixed x86_64 USER_HZ
+ * constant of 100 that todo 32's sysconf(_SC_CLK_TCK) reports (defined
+ * once, in src/misc/sysconf.c).
+ *
+ * struct tms mirrors the x86_64 kernel's __kernel_tms exactly: four longs
+ * in the same order (tms_utime, tms_stime, tms_cutime, tms_cstime), which
+ * is why src/sys/times.c hands the struct straight to SYS_times. The kernel
+ * writes all four words on every successful call, so no field is optional.
+ *
+ * The declaration carries no intent attribute: times() performs a syscall
+ * with side effects and reports failures through errno, so const/pure
+ * would be unsound (see the rationale in <sys/time.h>).
+ */
+
+#include <vlibc/features.h>
+
+#include <sys/types.h> /* clock_t */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#if VLIBC_LEVEL_GE(2)
+/* Level 2 (muslmimic): XSI process-CPU-time accounting. */
+
+/*
+ * CPU-time accounting for the calling process and its waited-for children,
+ * measured in clock ticks (CLK_TCK per second). tms_utime and tms_stime
+ * are the user and system CPU time of the calling process; tms_cutime and
+ * tms_cstime are the user and system CPU time consumed by children that
+ * have been waited for (all four zeroed before any child is waited on).
+ */
+struct tms
+{
+    clock_t tms_utime;  /* user CPU time of the calling process */
+    clock_t tms_stime;  /* system CPU time of the calling process */
+    clock_t tms_cutime; /* user CPU time of waited-for children */
+    clock_t tms_cstime; /* system CPU time of waited-for children */
+};
+
+/*
+ * Store the process CPU-time accounting through buf and return the number
+ * of clock ticks since an arbitrary fixed point in the past (the Linux
+ * kernel reports ticks since boot). Return (clock_t)-1 with errno set when
+ * buf points outside the address space.
+ */
+clock_t
+times(struct tms *buf);
+
+#endif /* VLIBC_LEVEL_GE(2) */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* VLIBC_SYS_TIMES_H */