diff options
Diffstat (limited to 'man-pages-posix-2003/man3p/pthread_mutex_timedlock.3p')
-rw-r--r-- | man-pages-posix-2003/man3p/pthread_mutex_timedlock.3p | 129 |
1 files changed, 129 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man3p/pthread_mutex_timedlock.3p b/man-pages-posix-2003/man3p/pthread_mutex_timedlock.3p new file mode 100644 index 0000000..5fe1465 --- /dev/null +++ b/man-pages-posix-2003/man3p/pthread_mutex_timedlock.3p @@ -0,0 +1,129 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_MUTEX_TIMEDLOCK" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_mutex_timedlock +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.SH NAME +pthread_mutex_timedlock \- lock a mutex (\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include <pthread.h> +.br +#include <time.h> +.br +.sp +int pthread_mutex_timedlock(pthread_mutex_t *restrict\fP \fImutex\fP\fB, +.br +\ \ \ \ \ \ const struct timespec *restrict\fP \fIabs_timeout\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_mutex_timedlock\fP() function shall lock the mutex +object referenced by \fImutex\fP. If the mutex is already +locked, the calling thread shall block until the mutex becomes available +as in the \fIpthread_mutex_lock\fP() function. If the mutex cannot +be locked without waiting for +another thread to unlock the mutex, this wait shall be terminated +when the specified timeout expires. +.LP +The timeout shall expire when the absolute time specified by \fIabs_timeout\fP +passes, as measured by the clock on which +timeouts are based (that is, when the value of that clock equals or +exceeds \fIabs_timeout\fP), or if the absolute time specified +by \fIabs_timeout\fP has already been passed at the time of the call. +.LP +If the Timers option is supported, the timeout shall be based on the +CLOCK_REALTIME clock; if the Timers option is not supported, +the timeout shall be based on the system clock as returned by the +\fItime\fP() function. +.LP +The resolution of the timeout shall be the resolution of the clock +on which it is based. The \fBtimespec\fP data type is +defined in the \fI<time.h>\fP header. +.LP +Under no circumstance shall the function fail with a timeout if the +mutex can be locked immediately. The validity of the +\fIabs_timeout\fP parameter need not be checked if the mutex can be +locked immediately. +.LP +As a consequence of the priority inheritance rules (for mutexes initialized +with the PRIO_INHERIT protocol), if a timed mutex +wait is terminated because its timeout expires, the priority of the +owner of the mutex shall be adjusted as necessary to reflect +the fact that this thread is no longer among the threads waiting for +the mutex. +.SH RETURN VALUE +.LP +If successful, the \fIpthread_mutex_timedlock\fP() function shall +return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +.LP +The \fIpthread_mutex_timedlock\fP() function shall fail if: +.TP 7 +.B EINVAL +The mutex was created with the protocol attribute having the value +PTHREAD_PRIO_PROTECT and the calling thread's priority is +higher than the mutex' current priority ceiling. +.TP 7 +.B EINVAL +The process or thread would have blocked, and the \fIabs_timeout\fP +parameter specified a nanoseconds field value less than +zero or greater than or equal to 1000 million. +.TP 7 +.B ETIMEDOUT +The mutex could not be locked before the specified timeout expired. +.sp +.LP +The \fIpthread_mutex_timedlock\fP() function may fail if: +.TP 7 +.B EINVAL +The value specified by \fImutex\fP does not refer to an initialized +mutex object. +.TP 7 +.B EAGAIN +The mutex could not be acquired because the maximum number of recursive +locks for \fImutex\fP has been exceeded. +.TP 7 +.B EDEADLK +The current thread already owns the mutex. +.sp +.LP +This function shall not return an error code of [EINTR]. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +The \fIpthread_mutex_timedlock\fP() function is part of the Threads +and Timeouts options and need not be provided on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_mutex_destroy\fP(), \fIpthread_mutex_lock\fP(), \fIpthread_mutex_trylock\fP(), +\fItime\fP(), the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI<pthread.h>\fP, \fI<time.h>\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |