This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH] Document pthread_[gs]etattr_default_np in the manual
- From: Siddhesh Poyarekar <siddhesh at redhat dot com>
- To: Roland McGrath <roland at hack dot frob dot com>
- Cc: libc-alpha at sourceware dot org
- Date: Sat, 15 Jun 2013 02:46:44 +0530
- Subject: Re: [PATCH] Document pthread_[gs]etattr_default_np in the manual
- References: <20130614030050 dot GF19582 at spoyarek dot pnq dot redhat dot com> <20130614210718 dot 031CF2C084 at topped-with-meat dot com>
On Fri, Jun 14, 2013 at 02:07:17PM -0700, Roland McGrath wrote:
> > +The @glibcadj{} provides non-standard API functions to set and get the default
>
> This should use @Theglibc{}.
>
> > +@deftypefun int pthread_getattr_default_np (pthread_attr_t *@var{attr})
> > +Get the default attribute values and set @var{attr} to match. This function
> > +is guaranteed not to fail.
> > +@end deftypefun
>
> If it's guaranteed not to fail it should return void. We want it to return
> an error code (int) for consistency with the rest of the API. That means
> we reserve the right for it to have ways to fail, even if there are no
> specific error conditions we document.
OK, then how about this:
-----
Get the default attribute values and set @var{attr} to match. This
function returns @math{0} on success and a non-zero error code on
failure.
-----
Do you want me to additionally mention that there are currently no
failure codes defined?
Siddhesh
* manual/threads.texi (Non-POSIX Extensions): New document
node. Document pthread_getattr_default_np and
pthread_setattr_default_np.
diff --git a/manual/threads.texi b/manual/threads.texi
index 9a1df1a..57e780e 100644
--- a/manual/threads.texi
+++ b/manual/threads.texi
@@ -9,6 +9,8 @@ This chapter describes the @glibcadj{} POSIX Thread implementation.
@menu
* Thread-specific Data:: Support for creating and
managing thread-specific data
+* Non-POSIX Extensions:: Additional functions to extend
+ POSIX Thread functionality
@end menu
@node Thread-specific Data
@@ -42,3 +44,41 @@ thread.
Associate the thread-specific @var{value} with @var{key} in the calling thread.
@end table
+
+@node Non-POSIX Extensions
+@section Non-POSIX Extensions
+
+In addition to implementing the POSIX API for threads, @theglibc{} provides
+additional functions and interfaces to provide functionality not specified in
+the standard.
+
+@menu
+* Default Thread Attributes:: Setting default attributes for
+ threads in a process.
+@end menu
+
+@node Default Thread Attributes
+@subsection Setting Process-wide defaults for thread attributes
+
+The @glibcadj{} provides non-standard API functions to set and get the default
+attributes used in the creation of threads in a process.
+
+@deftypefun int pthread_getattr_default_np (pthread_attr_t *@var{attr})
+Get the default attribute values and set @var{attr} to match. This
+function returns @math{0} on success and a non-zero error code on
+failure.
+@end deftypefun
+
+@deftypefun int pthread_getattr_default_np (pthread_attr_t *@var{attr})
+Set the default attribute values to match the values in @var{attr}. The
+function returns @math{0} on success and a non-zero error code on failure.
+The following error codes are defined for this function:
+
+@table @code
+@item EINVAL
+At least one of the values in @var{attr} does not qualify as valid for the
+attributes or the stack address is set in the attribute.
+@item ENOMEM
+The system does not have sufficient memory.
+@end table
+@end deftypefun