Skip to contentSkip to conversation

pthread_attr_setschedparam.3 : Describe EINVAL in ERRORS

PATCH In review Tobias Herzke 2 participants 2 messages Oct 11, 2014 – Feb 5, 2015 1 message not in the archive Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore

Tobias Herzke

author
#0 lore raw

PATCH 1/1 pthread_attr_setschedparam.3 : Describe EINVAL in ERRORS

The following example proves that the man page pthread_attr_setschedparam.3 is incorrect when it claims that the pthread_attr_setschedparam function always succeeds on linux:

#include <pthread.h>
#include <errno.h>
int main() {
pthread_attr_t attr;
struct sched_param p = {-1}; /* invalid priority */ if (pthread_attr_init(&attr) == 0)

    if (pthread_attr_setschedpolicy(&attr, SCHED_OTHER) == 0)
      if (pthread_attr_setschedparam(&attr, &p) == EINVAL)
	return 1;

return 0;
}

The program exits with exit code 1, therefore pthread_attr_setschedparam has returned error code EINVAL.

I could evoke this error on ubuntu 14.04, and verify it by examining the eglibc-2.19 source code. The function is implemented in file fbtl/pthread_attr_setschedparam.c. For error checking, it calls the helper function check_sched_priority_attr which is implemented inline in file ./fbtl/pthreadP.h. This function returns EINVAL if a range check fails.

The attached patch corrects the man page. The patch is against the current git master, 298f72af973e4bf3975d6a84369286b548e6fb63

man3/pthread_attr_setschedparam.3 +12 -5
index f3db870..8ea4f47 100644
@@ -86,15 +86,22 @@ to
 On success, these functions return 0;
 on error, they return a nonzero error number.
 .SH ERRORS
-POSIX.1 documents
+.BR pthread_attr_setschedparam ()
+can fail with the following error:
+.TP
 .B EINVAL
-and
+the priority specified in
+.I param
+does not make sense for the current scheduling policy of
+.IR attr .
+.PP
+POSIX.1 also documents an
 .B ENOTSUP
-errors for
+error for
 .BR pthread_attr_setschedparam ().
-On Linux these functions always succeed
+This value is never returned on Linux
 (but portable and future-proof applications should nevertheless
-handle a possible error return).
+handle this error return value).
 .\" .SH VERSIONS
 .\" Available since glibc 2.0.
 .SH ATTRIBUTES

A message that is not in the archive (sent off-list or not yet received): 54397F2C.7000008-l5l7mIzdFukkB/[email protected]

#2 lore raw
Quoted 19 lines · Tobias Herzke

The following example proves that the man page pthread_attr_setschedparam.3 is incorrect when it claims that the pthread_attr_setschedparam function always succeeds on linux:

#include <pthread.h>
#include <errno.h>

int main() {
   pthread_attr_t attr;
   struct sched_param p = {-1}; /* invalid priority */
   if (pthread_attr_init(&attr) == 0)
     if (pthread_attr_setschedpolicy(&attr, SCHED_OTHER) == 0)
       if (pthread_attr_setschedparam(&attr, &p) == EINVAL)
	return 1;
   return 0;
}

The program exits with exit code 1, therefore pthread_attr_setschedparam has returned error code EINVAL.

Quoted 8 lines

I could evoke this error on ubuntu 14.04, and verify it by examining the eglibc-2.19 source code. The function is implemented in file fbtl/pthread_attr_setschedparam.c. For error checking, it calls the helper function check_sched_priority_attr which is implemented inline in file ./fbtl/pthreadP.h. This function returns EINVAL if a range check fails.

The attached patch corrects the man page. The patch is against the current git master, 298f72af973e4bf3975d6a84369286b548e6fb63

Thanks, Tobias.

Patch applied.

Cheers,

Michael

=====

man3/pthread_attr_setschedparam.3 +12 -5
index f3db870..8ea4f47 100644
@@ -86,15 +86,22 @@ to
 On success, these functions return 0;
 on error, they return a nonzero error number.
 .SH ERRORS
-POSIX.1 documents
+.BR pthread_attr_setschedparam ()
+can fail with the following error:
+.TP
 .B EINVAL
-and
+the priority specified in
+.I param
+does not make sense for the current scheduling policy of
+.IR attr .
+.PP
+POSIX.1 also documents an
 .B ENOTSUP
-errors for
+error for
 .BR pthread_attr_setschedparam ().
-On Linux these functions always succeed
+This value is never returned on Linux
 (but portable and future-proof applications should nevertheless
-handle a possible error return).
+handle this error return value).
 .\" .SH VERSIONS
 .\" Available since glibc 2.0.
 .SH ATTRIBUTES
Signature · 7 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html