From owner-svn-src-stable@FreeBSD.ORG Sun May 16 11:03:47 2010 Return-Path: Delivered-To: svn-src-stable@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id A9E2B1065670; Sun, 16 May 2010 11:03:46 +0000 (UTC) (envelope-from jilles@FreeBSD.org) Received: from svn.freebsd.org (unknown [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 975408FC08; Sun, 16 May 2010 11:03:46 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.3/8.14.3) with ESMTP id o4GB3kHE081396; Sun, 16 May 2010 11:03:46 GMT (envelope-from jilles@svn.freebsd.org) Received: (from jilles@localhost) by svn.freebsd.org (8.14.3/8.14.3/Submit) id o4GB3k2N081392; Sun, 16 May 2010 11:03:46 GMT (envelope-from jilles@svn.freebsd.org) Message-Id: <201005161103.o4GB3k2N081392@svn.freebsd.org> From: Jilles Tjoelker Date: Sun, 16 May 2010 11:03:46 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-8@freebsd.org X-SVN-Group: stable-8 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r208138 - stable/8/share/man/man3 X-BeenThere: svn-src-stable@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: SVN commit messages for all the -stable branches of the src tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 16 May 2010 11:03:47 -0000 Author: jilles Date: Sun May 16 11:03:46 2010 New Revision: 208138 URL: http://svn.freebsd.org/changeset/base/208138 Log: MFC r207816: Document clock and pshared condvar attributes. Note: clock accepts CLOCK_VIRTUAL and CLOCK_PROF too, but this seems broken as it simply waits for the difference of the current and given value of the clock as if it were CLOCK_MONOTONIC. So document only CLOCK_REALTIME and CLOCK_MONOTONIC as allowed. Modified: stable/8/share/man/man3/Makefile stable/8/share/man/man3/pthread_cond_timedwait.3 stable/8/share/man/man3/pthread_condattr.3 Directory Properties: stable/8/share/man/man3/ (props changed) Modified: stable/8/share/man/man3/Makefile ============================================================================== --- stable/8/share/man/man3/Makefile Sun May 16 10:51:45 2010 (r208137) +++ stable/8/share/man/man3/Makefile Sun May 16 11:03:46 2010 (r208138) @@ -251,7 +251,11 @@ PTHREAD_MLINKS+=pthread_barrierattr.3 pt PTHREAD_MLINKS+=pthread_barrier_destroy.3 pthread_barrier_init.3 \ pthread_barrier_destroy.3 pthread_barrier_wait.3 PTHREAD_MLINKS+=pthread_condattr.3 pthread_condattr_destroy.3 \ - pthread_condattr.3 pthread_condattr_init.3 + pthread_condattr.3 pthread_condattr_init.3 \ + pthread_condattr.3 pthread_condattr_getclock.3 \ + pthread_condattr.3 pthread_condattr_setclock.3 \ + pthread_condattr.3 pthread_condattr_getpshared.3 \ + pthread_condattr.3 pthread_condattr_setpshared.3 PTHREAD_MLINKS+=pthread_getconcurrency.3 pthread_setconcurrency.3 PTHREAD_MLINKS+=pthread_multi_np.3 pthread_single_np.3 PTHREAD_MLINKS+=pthread_mutexattr.3 pthread_mutexattr_destroy.3 \ Modified: stable/8/share/man/man3/pthread_cond_timedwait.3 ============================================================================== --- stable/8/share/man/man3/pthread_cond_timedwait.3 Sun May 16 10:51:45 2010 (r208137) +++ stable/8/share/man/man3/pthread_cond_timedwait.3 Sun May 16 11:03:46 2010 (r208138) @@ -27,7 +27,7 @@ .\" .\" $FreeBSD$ .\" -.Dd July 28, 1998 +.Dd May 9, 2010 .Dt PTHREAD_COND_TIMEDWAIT 3 .Os .Sh NAME @@ -56,6 +56,11 @@ time specified in .Fa abstime , and the current thread reacquires the lock on .Fa mutex . +.Pp +The clock used to measure +.Fa abstime +can be specified during creation of the condition variable using +.Xr pthread_condattr_setclock 3 . .Sh RETURN VALUES If successful, the .Fn pthread_cond_timedwait @@ -87,7 +92,8 @@ was not locked by the calling thread. .Xr pthread_cond_destroy 3 , .Xr pthread_cond_init 3 , .Xr pthread_cond_signal 3 , -.Xr pthread_cond_wait 3 +.Xr pthread_cond_wait 3 , +.Xr pthread_condattr_setclock 3 .Sh STANDARDS The .Fn pthread_cond_timedwait Modified: stable/8/share/man/man3/pthread_condattr.3 ============================================================================== --- stable/8/share/man/man3/pthread_condattr.3 Sun May 16 10:51:45 2010 (r208137) +++ stable/8/share/man/man3/pthread_condattr.3 Sun May 16 11:03:46 2010 (r208138) @@ -26,12 +26,16 @@ .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ -.Dd April 28, 2000 +.Dd May 9, 2010 .Dt PTHREAD_CONDATTR 3 .Os .Sh NAME .Nm pthread_condattr_init , -.Nm pthread_condattr_destroy +.Nm pthread_condattr_destroy , +.Nm pthread_condattr_getclock , +.Nm pthread_condattr_setclock , +.Nm pthread_condattr_getpshared , +.Nm pthread_condattr_setpshared , .Nd condition attribute operations .Sh LIBRARY .Lb libpthread @@ -41,14 +45,17 @@ .Fn pthread_condattr_init "pthread_condattr_t *attr" .Ft int .Fn pthread_condattr_destroy "pthread_condattr_t *attr" +.Ft int +.Fn pthread_condattr_getclock "pthread_condattr_t * restrict attr" "clock_t * restrict clock_id" +.Ft int +.Fn pthread_condattr_setclock "pthread_condattr_t *attr" "clock_t clock_id" +.Ft int +.Fn pthread_condattr_getpshared "pthread_condattr_t * restrict attr" "int * restrict pshared" +.Ft int +.Fn pthread_condattr_setpshared "pthread_condattr_t *attr" "int pshared" .Sh DESCRIPTION Condition attribute objects are used to specify parameters to .Fn pthread_cond_init . -.Fx Ns 's -implementation of conditions does not support any non-default -attributes, so these functions are not very useful, though they are required -to be present by -.Tn POSIX . .Pp The .Fn pthread_condattr_init @@ -57,6 +64,52 @@ function initializes a condition attribu The .Fn pthread_condattr_destroy function destroys a condition attribute object. +.Pp +The +.Fn pthread_condattr_getclock +function will put the value of the clock attribute from +.Fa attr +into the memory area pointed to by +.Fa clock_id . +The +.Fn pthread_condattr_setclock +function will set the clock attribute of +.Fa attr +to the value specified in +.Fa clock_id . +The clock attribute affects the interpretation of +.Fa abstime +in +.Xr pthread_cond_timedwait 3 +and may be set to +.Dv CLOCK_REALTIME +(default) +or +.Dv CLOCK_MONOTONIC . +.Pp +The +.Fn pthread_condattr_getpshared +function will put the value of the process-shared attribute from +.Fa attr +into the memory area pointed to by +.Fa pshared . +The +.Fn pthread_condattr_setpshared +function will set the process-shared attribute of +.Fa attr +to the value specified in +.Fa pshared . +The argument +.Fa pshared +may have one of the following values: +.Bl -tag -width ".Dv PTHREAD_PROCESS_PRIVATE" +.It Dv PTHREAD_PROCESS_PRIVATE +The condition variable it is attached to may only be accessed by +threads in the same process as the one that created the object. +.It Dv PTHREAD_PROCESS_SHARED +The condition variable it is attached to may be accessed by +threads in processes other than the one that created the object. +.El .Sh RETURN VALUES If successful, these functions return 0. Otherwise, an error number is returned to indicate the error. @@ -77,8 +130,29 @@ function will fail if: Invalid value for .Fa attr . .El +.Pp +The +.Fn pthread_condattr_setclock +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified in +.Fa clock_id +is not one of the allowed values. +.El +.Pp +The +.Fn pthread_condattr_setpshared +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified in +.Fa pshared +is not one of the allowed values. +.El .Sh SEE ALSO -.Xr pthread_cond_init 3 +.Xr pthread_cond_init 3 , +.Xr pthread_cond_timedwait 3 .Sh STANDARDS The .Fn pthread_condattr_init @@ -86,3 +160,15 @@ and .Fn pthread_condattr_destroy functions conform to .St -p1003.1-96 +.Sh BUGS +The implementation of +condition variables +does not fully conform to +.St -p1003.2 +because the process-shared attribute is ignored; +if any value other than +.Dv PTHREAD_PROCESSES_PRIVATE +is specified in a call to +.Fn pthread_condattr_setpshared , +it will return +.Er EINVAL .