Is it time to expose timespecsub and friends to userland?

[Ian Lepore]

On Fri, 2018-03-16 at 11:01 -0600, Alan Somers wrote:
> There are at least 19 system calls that have timeout arguments specified as
> struct timespec [1].  "struct stat" describes file timestamps as timespecs
> as well [2].  setsockopt(2),  sched_rr_get_interval(2),
> geom_stats_snapshot_timestamp(3) and pmclog_read(3) use timespecs for other
> purposes.  The sysctl node kern.crypto_stats exposes timespecs.  sudo
> records timespecs in its timestamp files.  Who know how many other ports do
> something similar; I'm not going to grep them all.
> 
> And yet, FreeBSD provides no way to manipulate this structure.  Every
> program that uses them has to roll its own version of pretty much the same
> functions.  NetBSD does [3], and has for a long time.  In fact, NetBSD's
> timespecsub is old enough to drink [4].  But in FreeBSD, those functions
> languish inside of an "#ifdef KERNEL".  phk added them in r35029 with the
> comment "XXX: These may change!".  But it's been nearly 20 years, so I
> don't think they're going to change any more.
> 
> Shall we finally expose them to userland and add a man page?  Let the
> bikeshed begin!  If the flame isn't too bad, I'll do it.
> 
> -Alan
> 
> [1] syscalls that use timespec timeouts include: aio_suspend(2),
> aio_waitcomplete(2), nanosleep(2), clock_nanosleep(2), kevent(2),
> mq_timedreceive(2), mq_timedsend(2), ppoll(2), pselect(2), recvmmsg(2),
> sigtimedwait(2), thr_suspend(2), cnd_timedwait(3), mtx_timedlock(3),
> thrd_sleep(3), pthread_mutex_timedlock(3), pthread_cond_timedwait(3),
> sem_timedwait(3), sem_clockwait_np(3).
> 
> [2] syscalls that use timespecs for file timestamp related purposes:
> stat(2), fstat(2), futimens(2), utimensat(2), lstat(2)
> 
> [3] http://netbsd.gw.com/cgi-bin/man-cgi?timespecclear+3+NetBSD-7.0
> 
> [4]
> http://cvsweb.netbsd.org/bsdweb.cgi/src/sys/sys/time.h.diff?r1=1.19&r2=1.20&only_with_tag=MAIN&f=h

IMO, it's long overdue.  I've never understood why they weren't exposed
on the day the were added.

-- Ian