Module Name: src
Committed By: jruoho
Date: Thu Jul 8 06:47:50 UTC 2010
Modified Files:
src/lib/libpthread: pthread_attr.3
Log Message:
Rewrite and include a short summary.
To generate a diff of this commit:
cvs rdiff -u -r1.18 -r1.19 src/lib/libpthread/pthread_attr.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libpthread/pthread_attr.3
diff -u src/lib/libpthread/pthread_attr.3:1.18 src/lib/libpthread/pthread_attr.3:1.19
--- src/lib/libpthread/pthread_attr.3:1.18 Wed Jul 7 16:22:30 2010
+++ src/lib/libpthread/pthread_attr.3 Thu Jul 8 06:47:49 2010
@@ -1,6 +1,6 @@
-.\" $NetBSD: pthread_attr.3,v 1.18 2010/07/07 16:22:30 jruoho Exp $
+.\" $NetBSD: pthread_attr.3,v 1.19 2010/07/08 06:47:49 jruoho Exp $
.\"
-.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
+.\" Copyright (c) 2002, 2010 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
@@ -53,7 +53,7 @@
.\"
.\" $FreeBSD: src/lib/libpthread/man/pthread_attr.3,v 1.11 2002/09/16 19:29:28 mini Exp $
.\"
-.Dd October 6, 2009
+.Dd July 8, 2010
.Dt PTHREAD_ATTR 3
.Os
.Sh NAME
@@ -73,53 +73,83 @@
.Fn pthread_create .
One attribute object can be used in multiple calls to
.Fn pthread_create ,
-with or without modifications between calls.
+with or without modifications between the calls.
+The
+.Vt pthread_attr_t
+type is an opaque representation of the thread attributes;
+any access to the object other than via the described
+.Fn pthread_attr_*
+functions may result undefined behavior.
.Pp
The
.Fn pthread_attr_init
function initializes
.Fa attr
-with all the default thread attributes.
+with the default thread attributes used in the implementation.
+Depending on the implementation, undefined behavior may follow
+if an uninitialized thread attribute object is used with some of
+the thread attribute functions.
+It is therefore a good practice to always use
+.Fn pthread_attr_init ,
+even if this might be unnecessary.
+Undefined behavior may also follow if an already initialized
+.Fa attr
+is used with
+.Fn pthread_attr_init .
.Pp
-The
-.Fn pthread_attr_destroy
-function destroys
-.Fa attr .
+When the attribute object is no longer needed,
+it should be destroyed by using
+.Fn pthread_attr_destroy .
+The function has no effect on threads that
+were created by using a given attribute object.
+A destroyed
+.Fa attr
+can be reinitialized using
+.Fn pthread_attr_init ,
+but all other actions with the destroyed object are unspecified.
.Pp
-The
-.Fn pthread_attr_set*
-functions set the attribute that corresponds to each function name.
+The following standard thread attribute functions are available:
+.Bl -column -offset indent "pthread_attr_getinheritsched " "XXX"
+.It Sy Function Ta Sy Description
+.It Xr pthread_attr_getdetachstate 3 Ta thread detach state
+.It Xr pthread_attr_getguardsize 3 Ta thread guard size
+.It Xr pthread_attr_getinheritsched 3 Ta inherit scheduler attribute
+.It Xr pthread_attr_getschedparam 3 Ta thread scheduling parameter
+.It Xr pthread_attr_getschedpolicy 3 Ta thread scheduling policy
+.It Xr pthread_attr_getscope 3 Ta thread contention scope
+.It Xr pthread_attr_getstack 3 Ta thread stack
+.It Xr pthread_attr_getstacksize 3 Ta thread stack size
+.It Xr pthread_attr_getstackaddr 3 Ta thread stack address
+.El
.Pp
-The
+Each listed
.Fn pthread_attr_get*
-functions copy the value of the attribute that corresponds to each function name
-to the location pointed to by the second function parameter.
+function contains a
+.Fn pthread_attr_set*
+counterpart.
+In addition, the following
+.Nx
+specific extensions are available:
+.Bl -column -offset indent "pthread_attr_getinheritsched " "XXX"
+.It Sy Function Ta Sy Description
+.It Xr pthread_attr_get_np 3 Ta attributes of a running thread
+.It Xr pthread_attr_getname_np 3 Ta descriptive name of an attribute
+.El
.Sh RETURN VALUES
If successful, these functions return 0.
Otherwise, an error number is returned to indicate the error.
.Sh ERRORS
+No errors are defined for
.Fn pthread_attr_init
-may fail if:
-.Bl -tag -width Er
-.It Bq Er ENOMEM
-Out of memory.
-.El
-.Pp
-.Fn pthread_attr_destroy
-may fail if:
-.Bl -tag -width Er
-.It Bq Er EINVAL
-The value specified by
-.Fa attr
-is invalid.
-.El
+and
+.Fn pthread_attr_destroy .
.Sh SEE ALSO
.Xr pthread_create 3 ,
.Xr pthread_join 3
.Sh STANDARDS
-The
+Both
.Fn pthread_attr_init
and
.Fn pthread_attr_destroy
-functions conform to
+conform to
.St -p1003.1-96 .
