6501 Implement pthread_attr_get_np() interface

Reviewed by: Jerry Jelinek <jerry.jelinek@joyent.com>
Reviewed by: Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
Approved by: Garrett D'Amore <garrett@damore.org>

3 files changed, 201 insertions, 6 deletions

diff --git a/usr/src/man/man3c/Makefile b/usr/src/man/man3c/Makefile
index 67861882e4..eebbda3288 100644
--- a/usr/src/man/man3c/Makefile
+++ b/usr/src/man/man3c/Makefile
@@ -304,6 +304,7 @@ MANFILES= 	__fbufsize.3c					\
 	 	pthread_attr_getstack.3c			\
 	 	pthread_attr_getstackaddr.3c			\
 	 	pthread_attr_getstacksize.3c			\
+		pthread_attr_get_np.3c				\
 	 	pthread_attr_init.3c				\
 	 	pthread_barrier_destroy.3c			\
 	 	pthread_barrier_wait.3c				\
diff --git a/usr/src/man/man3c/pthread_attr_get_np.3c b/usr/src/man/man3c/pthread_attr_get_np.3c
new file mode 100644
index 0000000000..8ffb28c0fc
--- /dev/null
+++ b/usr/src/man/man3c/pthread_attr_get_np.3c
@@ -0,0 +1,198 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd Feb 07, 2015
+.Dt PTHREAD_ATTR_GET_NP 3C
+.Os
+.Sh NAME
+.Nm pthread_attr_get_np
+.Nd get pthread attributes of a running thread
+.Sh SYNOPSIS
+.In pthread.h
+.Ft int
+.Fo pthread_attr_get_np
+.Fa "pthread_t thread"
+.Fa "pthread_attr_t *attr"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn pthread_attr_get_np
+function provides a way to get the attributes of the thread
+.Fa thread
+after it has been created. This function is most commonly used to obtain
+the actual location and size of a thread's stack.
+.Pp
+The attributes pointer,
+.Fa attr ,
+will be filled in with the current attributes for the thread. The
+attributes should be allocated by a call to
+.Xr pthread_attr_init 3C
+prior to calling the
+.Fn pthrad_attr_get_np
+function. When
+.Fa attr
+is done being used, it should be destroyed through a call to
+.Xr pthread_attr_destroy 3C .
+.Pp
+The attributes of the thread
+.Fa thread
+will be the same as those passed in at the time
+.Xr pthread_create 3C
+was called (or the default set if none were specified), except that the
+following values will be updated:
+.Bl -tag -width Sy
+.It Sy Thread Stack Size
+If no explicit stack size was specified, then
+.Fa attr
+will contain the actual size of the stack.
+.Pp
+If the size of the stack was specified, then it may have been changed to
+ensure that the required alignment of the platform is satisfied.
+.It Sy The Stack Address
+If no stack address was specified, then
+.Fa attr
+will contain the actual address of the stack that the system allocated
+for the thread.
+.It Sy Thread Detach State
+The detach state, whether or not the thread may be joined by a call to
+.Xr pthread_join 3C ,
+may have changed since the process was created due to a call to
+.Xr pthread_detach 3C .
+.Fa attr
+will reflect the current setting of
+.Fa thread .
+.It Sy Thread Scheduling Parameter
+The scheduling parameter attribute will be updated with the current
+scheduling parameter of
+.Fa thread .
+This is the same information as available through
+.Xr pthread_getschedparam 3C
+and it is the preferred interface for obtaining that information.
+.It Sy Thread Scheduling Policy
+The scheduling policy attribute of
+.Fa attr
+will be updated with the current scheduling policy being applied to the
+thread. This may have changed, for example, due to a call to
+.Xr pthread_setschedparam 3C .
+As with the thread's scheduling parameter, the preferred interface for
+obtaining this information is by using
+.Xr pthread_getschedparam 3C .
+.It Sy Thread Guard Size
+The value of the guard size attribute for the thread will be updated to
+reflect the actual size of the guard installed for
+.Fa thread .
+For more information on the guard size of a thread and its purpose, see
+.Xr pthread_attr_getguardsize 3C .
+.El
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn pthread_attr_get_np
+and
+.Fn pthread_getattr_np
+functions return
+.Sy 0 .
+Otherwise, an error number is returned to indicate the error.
+.Sh EXAMPLES
+The following program demonstrates how to use these functions to get
+the location and stack size of a newly created thread.
+.Bd -literal
+#include <assert.h>
+#include <errno.h>
+#include <pthread.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static pthread_t g_thr;
+
+void *
+print_stackinfo(void *arg)
+{
+	int ret;
+	pthread_attr_t attr;
+	pthread_t *thrp = arg;
+	void *stk;
+	size_t stksize;
+
+	if (pthread_attr_init(&attr) != 0) {
+		fprintf(stderr, "failed to init attr: %s\\n",
+		    strerror(errno));
+		exit(1);
+	}
+
+	if (pthread_attr_get_np(*thrp, &attr) != 0) {
+		fprintf(stderr, "failed to get thread attributes: %s\\n",
+		    strerror(errno));
+		exit(1);
+	}
+
+	ret = pthread_attr_getstackaddr(&attr, &stk);
+	assert(ret == 0);
+	ret = pthread_attr_getstacksize(&attr, &stksize);
+	assert(ret == 0);
+	(void) printf("stack base is at %p, it is %d bytes large\\n",
+	    stk, stksize);
+	return (NULL);
+}
+
+int
+main(void)
+{
+	int ret;
+
+	if ((ret = pthread_create(&g_thr, NULL, print_stackinfo,
+	    &g_thr) != 0)) {
+		fprintf(stderr, "failed to create a thread: %s\\n",
+		    strerror(errno));
+		exit(1);
+	}
+
+	pthread_join(g_thr, NULL);
+	return (0);
+}
+.Ed
+.Sh ERRORS
+The
+.Fn pthread_attr_get_np
+function will fail if:
+.Bl -tag -width Er
+.It Er EINVAL
+The pthread_attr_t object
+.Fa attr
+was not properly initialized with a call to
+.Xr pthread_attr_init 3C .
+.It Er ESRCH
+No thread could be found corresponding to the specified thread ID,
+.Fa thread .
+.El
+.Sh INTERFACE STABILITY
+.Sy Committed
+.Sh MT-LEVEL
+.Sy MT-Safe
+.Sh SEE ALSO
+.Xr pthread_attr_destroy 3C ,
+.Xr pthread_attr_getdetachstate 3C ,
+.Xr pthread_attr_getguardsize 3C ,
+.Xr pthread_attr_getinheritsched 3C ,
+.Xr pthread_attr_getschedparam 3C ,
+.Xr pthread_attr_getschedpolicy 3C ,
+.Xr pthread_attr_getscope 3C ,
+.Xr pthread_attr_getstackaddr 3C ,
+.Xr pthread_attr_getstacksize 3C ,
+.Xr pthread_attr_init 3C ,
+.Xr pthread_create 3C ,
+.Xr pthread_detach 3C ,
+.Xr pthread_getschedparam 3C ,
+.Xr pthread_setschedparam 3C ,
+.Xr attributes 5 ,
+.Xr threads 5
diff --git a/usr/src/man/man3c/pthread_attr_init.3c b/usr/src/man/man3c/pthread_attr_init.3c
index 5d5bce0420..6dd32ecee7 100644
--- a/usr/src/man/man3c/pthread_attr_init.3c
+++ b/usr/src/man/man3c/pthread_attr_init.3c
@@ -9,7 +9,7 @@
 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
-.TH PTHREAD_ATTR_INIT 3C "Apr 1, 2008"
+.TH PTHREAD_ATTR_INIT 3C "Dec 10, 2015"
 .SH NAME
 pthread_attr_init, pthread_attr_destroy \- initialize or destroy threads
 attribute object
@@ -28,7 +28,6 @@ cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ]
 .fi
 
 .SH DESCRIPTION
-.sp
 .LP
 The function \fBpthread_attr_init()\fR initializes a thread attributes object
 \fIattr\fR with the default value for all of the individual attributes used by
@@ -73,13 +72,11 @@ implementation may cause \fBpthread_attr_destroy()\fR to set \fIattr\fR to an
 implementation-dependent invalid value. The behavior of using the attribute
 after it has been destroyed is undefined.
 .SH RETURN VALUES
-.sp
 .LP
 Upon successful completion, \fBpthread_attr_init()\fR and
 \fBpthread_attr_destroy()\fR return a value of  \fB0\fR. Otherwise, an error
 number is returned to indicate the error.
 .SH ERRORS
-.sp
 .LP
 The  \fBpthread_attr_init()\fR function will fail if:
 .sp
@@ -104,7 +101,6 @@ The  \fBpthread_attr_destroy()\fR function may fail if:
 .RE
 
 .SH ATTRIBUTES
-.sp
 .LP
 See \fBattributes\fR(5) for descriptions of the following attributes:
 .sp
@@ -124,9 +120,9 @@ Standard	See \fBstandards\fR(5).
 .TE
 
 .SH SEE ALSO
-.sp
 .LP
 \fBsysconf\fR(3C), \fBpthread_attr_getdetachstate\fR(3C),
+\fBpthread_attr_get_np\fR(3C),
 \fBpthread_attr_getguardsize\fR(3C), \fBpthread_attr_getinheritsched\fR(3C),
 \fBpthread_attr_getschedparam\fR(3C), \fBpthread_attr_getschedpolicy\fR(3C),
 \fBpthread_attr_getscope\fR(3C), \fBpthread_attr_getstackaddr\fR(3C),