[src/trunk]: src/lib/libpthread Rewrite and include a short summary.

[jruoho <jruoho%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/5ff66c2fa234
branches:  trunk
changeset: 756177:5ff66c2fa234
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Thu Jul 08 06:47:49 2010 +0000

description:
Rewrite and include a short summary.

diffstat:

 lib/libpthread/pthread_attr.3 |  92 ++++++++++++++++++++++++++++--------------
 1 files changed, 61 insertions(+), 31 deletions(-)

diffs (133 lines):

diff -r 9adbea6f1cfe -r 5ff66c2fa234 lib/libpthread/pthread_attr.3
--- a/lib/libpthread/pthread_attr.3     Thu Jul 08 06:13:58 2010 +0000
+++ b/lib/libpthread/pthread_attr.3     Thu Jul 08 06:47:49 2010 +0000
@@ -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 .