Warn on clock use.

doc/obsolete-stuff

@@ -53,6 +53,20 @@ similarly poorly named flag O_CREAT that does what you need.
 
 Sortix currently implement this function for compatibility reasons.
 
+clock
+-----
+
+The clock() function suffers from overflow issues where it wraps around and the
+caller has to handle that, meaning it's not suitable for measuring long
+intervals. Converting a clock interval to seconds it also bothersome and
+requires division by CLOCKS_PER_SEC.
+
+You should use clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &ts) instead as it has no
+overflow issues, provides nanosecond precision if available, and can be combined
+with APIs such as Sortix's <timespec.h> for convenient computing.
+
+Sortix currently implements this function for compatibility reasons.
+
 ctime, ctime_r
 --------------
 

libc/include/time.h

@@ -120,6 +120,9 @@ char* asctime(const struct tm*);
 __attribute__((__warning__("asctime_r() is obsolete, use strftime()")))
 #endif
 char* asctime_r(const struct tm* __restrict, char* __restrict);
+#if !defined(__is_sortix_libc) /* not a warning inside libc */
+__attribute__((__warning__("clock() is obsolete, use clock_gettime()")))
+#endif
 clock_t clock(void);
 /* TODO: clock_getcpuclockid */
 int clock_getres(clockid_t, struct timespec*);