From 28e3357884527e90cfc843e4a95d66661669fbf4 Mon Sep 17 00:00:00 2001 From: Eric van Gyzen Date: Fri, 3 Jun 2016 14:30:32 +0000 Subject: [PATCH] Improve errno documentation in pthread_create(3) and thr_new(2) Add some missing errno values to thr_new(2) and pthread_create(3). In particular, EDEADLK was not documented in the latter. While I'm here, improve some English and cross-references. Reviewed by: kib Sponsored by: Dell Inc. Differential Revision: https://reviews.freebsd.org/D6663 --- lib/libc/sys/cpuset_getaffinity.2 | 4 ++- lib/libc/sys/thr_new.2 | 11 +++++-- share/man/man3/pthread_attr_affinity_np.3 | 6 ++-- share/man/man3/pthread_create.3 | 35 +++++++++++++++++------ 4 files changed, 41 insertions(+), 15 deletions(-) diff --git a/lib/libc/sys/cpuset_getaffinity.2 b/lib/libc/sys/cpuset_getaffinity.2 index 7032d2ec7a0..c379518214b 100644 --- a/lib/libc/sys/cpuset_getaffinity.2 +++ b/lib/libc/sys/cpuset_getaffinity.2 @@ -25,7 +25,7 @@ .\" .\" $FreeBSD$ .\" -.Dd October 20, 2015 +.Dd June 2, 2016 .Dt CPUSET_GETAFFINITY 2 .Os .Sh NAME @@ -114,6 +114,8 @@ to the value in The following error codes may be set in .Va errno : .Bl -tag -width Er +.\" When changing this list, consider updating share/man/man3/pthread_create.3, +.\" since that function can return any of these errors. .It Bq Er EINVAL The .Fa level diff --git a/lib/libc/sys/thr_new.2 b/lib/libc/sys/thr_new.2 index 1de5f92ad56..27f4191ae8b 100644 --- a/lib/libc/sys/thr_new.2 +++ b/lib/libc/sys/thr_new.2 @@ -28,7 +28,7 @@ .\" .\" $FreeBSD$ .\" -.Dd June 1, 2016 +.Dd June 2, 2016 .Dt THR_NEW 2 .Os .Sh NAME @@ -175,6 +175,8 @@ The .Fn thr_new operation returns the following errors: .Bl -tag -width Er +.\" When changing this list, consider updating share/man/man3/pthread_create.3, +.\" since that function can return any of these errors. .It Bq Er EFAULT The memory pointed to by the .Fa param @@ -188,7 +190,7 @@ or .Fa rtp arguments is not valid. .It Bq Er EFAULT -Specified stack base is invalid, or the kernel was unable to put required +The specified stack base is invalid, or the kernel was unable to put required initial data on the stack. .It Bq Er EINVAL The @@ -205,6 +207,9 @@ member is not and specifies invalid scheduling parameters. .It Bq Er EINVAL The specified TLS base is invalid. +.It Bq Er EPERM +The caller does not have permission to set the scheduling parameters or +scheduling policy. .It Bq Er EPROCLIM Creation of the new thread would exceed the .Dv RACCT_NTHR @@ -216,7 +221,7 @@ Creation of the new thread would exceed the .Xr sysctl 2 limit. .It Bq Er ENOMEM -No kernel memory to allocate for the new thread structures. +There was not enough kernel memory to allocate the new thread structures. .El .Sh SEE ALSO .Xr ps 1 , diff --git a/share/man/man3/pthread_attr_affinity_np.3 b/share/man/man3/pthread_attr_affinity_np.3 index ee63e7d71e1..56e53297f7b 100644 --- a/share/man/man3/pthread_attr_affinity_np.3 +++ b/share/man/man3/pthread_attr_affinity_np.3 @@ -25,7 +25,7 @@ .\" .\" $FreeBSD$ .\" -.Dd January 8, 2010 +.Dd June 2, 2016 .Dt PTHREAD_ATTR_AFFINITY_NP 3 .Os .Sh NAME @@ -132,8 +132,8 @@ Insufficient memory exists to store the cpuset mask. .Xr cpuset 2 , .Xr cpuset_getid 2 , .Xr cpuset_setid 2 , -.Xr pthread_get_affinity_np 3 , -.Xr pthread_set_affinity_np 3 +.Xr pthread_getaffinity_np 3 , +.Xr pthread_setaffinity_np 3 .Sh STANDARDS The .Nm pthread_attr_getaffinity_np diff --git a/share/man/man3/pthread_create.3 b/share/man/man3/pthread_create.3 index 58bef13629c..43d9ed2fcae 100644 --- a/share/man/man3/pthread_create.3 +++ b/share/man/man3/pthread_create.3 @@ -30,7 +30,7 @@ .\" .\" $FreeBSD$ .\" -.Dd March 15, 2014 +.Dd June 2, 2016 .Dt PTHREAD_CREATE 3 .Os .Sh NAME @@ -101,22 +101,41 @@ indicate the error. .Sh ERRORS The .Fn pthread_create -function will fail if: +function can return any of the following errors: .Bl -tag -width Er +.It Bq Er ENOMEM +The system lacked the necessary resources to create another thread. .It Bq Er EAGAIN -The system lacked the necessary resources to create another thread, or -the system-imposed limit on the total number of threads in a process -[PTHREAD_THREADS_MAX] would be exceeded. +The system-imposed limit on the total number of threads in a process +.Dv [PTHREAD_THREADS_MAX] +would be exceeded. +.It Bq Er EAGAIN +The +.Dv RACCT_NTHR +limit would be exceeded; see +.Xr racct 2 . .It Bq Er EPERM -The caller does not have appropriate permission to set the required scheduling -parameters or scheduling policy. +The caller does not have permission to set the scheduling parameters or +scheduling policy. .It Bq Er EINVAL -The value specified by +A value specified by .Fa attr is invalid. +.It Bq Er EDEADLK +The CPU set specified by +.Fa attr +would prevent the thread from running on any CPU. +.It Bq Er EFAULT +The stack base specified by +.Fa attr +is invalid, or the kernel was unable to put required +initial data on the stack. .El .Sh SEE ALSO +.Xr cpuset_setaffinity 2 , .Xr fork 2 , +.Xr racct 2 , +.Xr thr_new 2 , .Xr pthread_attr 3 , .Xr pthread_cancel 3 , .Xr pthread_cleanup_pop 3 , -- 2.45.2