o Implement pthread_mutex_timedlock(), which does not block indefinitely on

a mutex locked by another thread.
o document it: pthread_mutex_timedlock(3)

lib/libthr/thread/thr_mutex.c

@@ -93,6 +93,7 @@ __weak_reference(__pthread_mutex_unlock, pthread_mutex_unlock);
 /* No difference between libc and application usage of these: */
 __weak_reference(_pthread_mutex_init, pthread_mutex_init);
 __weak_reference(_pthread_mutex_destroy, pthread_mutex_destroy);
+__weak_reference(_pthread_mutex_timedlock, pthread_mutex_timedlock);
 
 
 /*
@@ -555,6 +556,28 @@ _pthread_mutex_lock(pthread_mutex_t *mutex)
 	return (ret);
 }
 
+int
+_pthread_mutex_timedlock(pthread_mutex_t *mutex, const struct timespec *abstime)
+{
+	int error;
+
+	error = 0;
+	if (_thread_initial == NULL)
+		_thread_init();
+
+	/*
+	 * Initialize it if it's a valid statically inited mutex.
+	 */
+	if (mutex == NULL)
+		error = EINVAL;
+	else if ((*mutex != PTHREAD_MUTEX_INITIALIZER) ||
+	    ((error = mutex_init(mutex, 0)) == 0))
+		error = mutex_lock_common(mutex, 0, abstime);
+
+	PTHREAD_ASSERT(error != EINTR, "According to SUSv3 this function shall not return an error code of EINTR");
+	return (error);
+}
+
 int
 __pthread_mutex_unlock(pthread_mutex_t * mutex)
 {
@@ -1417,6 +1440,15 @@ get_mcontested(pthread_mutex_t mutexp, const struct timespec *abstime)
 {
 	int error;
 
+	/*
+	 * If the timeout is invalid this thread is not allowed
+	 * to block;
+	 */
+	if (abstime != NULL) {
+		if (abstime->tv_nsec < 0 || abstime->tv_nsec >= 1000000000)
+			return (EINVAL);
+	}
+
 	/*
 	 * Put this thread on the mutex's list of waiting threads.
 	 * The lock on the thread ensures atomic (as far as other

share/man/man3/Makefile

@@ -3,6 +3,11 @@
 
 MAN=	assert.3 bitstring.3 end.3 fpgetround.3 intro.3 pthread.3 queue.3 \
 	stdarg.3 sysexits.3 timeradd.3 tree.3
+
+.ifndef NOLIBC_R || NOLIBPTHREAD || NOLIBTHR
+MAN+=	pthread_mutex_timedlock.3
+.endif
+
 MLINKS+=bitstring.3 bit_alloc.3 bitstring.3 bit_clear.3 \
 	bitstring.3 bit_decl.3 bitstring.3 bit_ffc.3 bitstring.3 bit_ffs.3 \
 	bitstring.3 bit_nclear.3 bitstring.3 bit_nset.3 bitstring.3 bit_set.3 \

share/man/man3/pthread.3

@@ -274,6 +274,11 @@ Initialize a mutex with specified attributes.
 Lock a mutex and block until it becomes available.
 .It Xo
 .Ft int
+.Fn pthread_mutex_timedlock "pthread_mutex_t *mutex" "const struct timespec *abstime"
+.Xc
+Lock a mutex and block until it becomes available or until the timeout expires.
+.It Xo
+.Ft int
 .Fn pthread_mutex_trylock "pthread_mutex_t *mutex"
 .Xc
 Try to lock a mutex, but don't block if the mutex is locked by another thread,