sem_open.3 and sem_overview.7
PATCH 1/1 sem_open.3 and sem_overview.7
Dear Michael,
I have here two small patches for the man pages sem_open(3)
and sem_overview(7). They result from a recent discussion in c.o.l.d.a where someone had problems creating a named semaphore using a name of "/tmp/somename". From the man pages it's not absolutely clear that this isn't allowed. Moreover, one gets an errno of ENOENT in this case which doesn't seem to be covered in sem_open(3). Thus I made a modification in sem_overview(7) so that it now says that slashes embedded into to the name are not allowed and to sem_open(3) to say that ENOENT can also be the result of having O_CREAT set in oflag but using an invalid name.
The actual situation is a bit more complicated as a look at
the glibc code for sem_open() shows (you can actually use a slash in the name, e.g. "/aaa/bbb", but then a directory named sem.aaa you have write permissions for must already exist in /dev/shm, moreover, the slash at the start isn't needed). But I guess that isn't of much relevance to the user and probably is better left untold since putting it into writing might make it more difficult to change the behaviour later on.
Here's the diff for sem_overview(7):
----------8<------------------------------------------------------
sem_overview.7.new renamed from sem_overview.7 +4 -1
@@ -48,6 +48,9 @@ Two processes can operate on the same named semaphore by passing the same name to .BR sem_open (3). +Note that +.IR /somename +may not contain slashes except the required one at the very start. The .BR sem_open (3)
@@ -113,7 +116,7 @@ normally mounted under .IR /dev/shm , with names of the form -.IR \fBsem.\fPname . +.IR \fBsem.\fPsomename . Since Linux 2.6.19, ACLs can be placed on files under this directory, to control object permissions on a per-user and per-group basis.
----------8<------------------------------------------------------
and here's the one for sem_open(3):
----------8<------------------------------------------------------
sem_open.3.new renamed from sem_open.3 +9 -2
@@ -149,10 +149,17 @@ The .B O_CREAT flag was not specified in -.IR oflag , +.IR oflag and no semaphore with this .I name -exists. +exists, or the +.B O_CREAT +flag +was set in +.IR oflag +but +.I name +wasn't well-formed. .TP .B ENOMEM Insufficient memory.
----------8<------------------------------------------------------
Both are against your newest version 3.18.
Best regards, Jens
Signature · 6 lines
\ Jens Thoms Toerring ________ [email protected] \_______________________________ http://toerring.de -- 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
A message that is not in the archive (sent off-list or not yet received): [email protected]
Hello Jens,
Thanks for this very thorough report!
Quoted 7 lines · Jens Thoms Toerring
Dear Michael,
I have here two small patches for the man pages
sem_open(3)
andsem_overview(7). They result from a recent discussion in c.o.l.d.a where someone had problems creating a named semaphore using a name of "/tmp/somename". From the man pages it's not absolutely clear that this isn't allowed.
Agreed.
Quoted 7 lines
Moreover, one gets an
errno of ENOENT in this case which doesn't seem to be covered insem_open(3). Thus I made a modification insem_overview(7)so that it now says that slashes embedded into to the name are not allowed and tosem_open(3)to say that ENOENT can also be the result of havingO_CREATset in oflag but using an invalid name.
See my comments below.
Quoted 5 lines
The actual situation is a bit more complicated as a look at
the glibc code forsem_open()shows (you can actually use a slash in the name, e.g. "/aaa/bbb", but then a directory named sem.aaa you have write permissions for must already exist in/dev/shm, moreover, the slash at the start isn't needed).
Thanks for filling in that background. My reading of the glibc source, plus testing, confirms what you say.
Quoted 4 lines
But I guess that
isn't of much relevance to the user and probably is better left untold since putting it into writing might make it more difficult to change the behaviour later on.
Indeed, this is best left untold, since it's non-standard, non-portable behavior that could change.
sem_overview.7.new line 53
Quoted 12 lines
Here's the diff for
sem_overview(7):----------8<------------------------------------------------------
sem_overview.7.new renamed from sem_overview.7 +3
-0@@ -48,6 +48,9 @@ Two processes can operate on the same named semaphore by passing the same name to .BR sem_open (3). +Note that +.IR /somename +may not contain slashes except the required one at the very start.
In fact, I made a bigger fix, stating:
A named semaphore is identified by a name of the form /somename; that is, a null-terminated string of up to NAME_MAX+1 (i.e., 256) characters consisting of an initial slash, followed by one or more characters, none of which are slashes.
sem_overview.7.new line 119
Quoted 8 lines
sem_overview.7.new renamed from sem_overview.7 +1
-1The .BR sem_open (3)@@ -113,7 +116,7 @@ normally mounted under .IR /dev/shm , with names of the form -.IR \fBsem.\fPname . +.IR \fBsem.\fPsomename .
Yep -- made that change.
Quoted 16 lines
sem_overview.7.new renamed from sem_overview.7 +0
-1Since Linux 2.6.19, ACLs can be placed on files under this directory, to control object permissions on a per-user and per-group basis. ----------8<------------------------------------------------------and here's the one for
sem_open(3):----------8<------------------------------------------------------
sem_open.3.new renamed from sem_open.3 +1
-1@@ -149,10 +149,17 @@ The .B O_CREAT flag was not specified in -.IR oflag , +.IR oflag and no semaphore with this
sem_open.3.new line 162
Quoted 10 lines
sem_open.3.new renamed from sem_open.3 +8
-1.I name -exists. +exists, or the +.B O_CREAT +flag +was set in +.IR oflag +but +.I name +wasn't well-formed.
I applied this change, with slight edits.
The changes will be in man-pages-3.19.
In fact, your report also caused me to look at the pages for POSIX message queues and shared memory, and make analogous changes there (mq_overview.7, mq_open.3, shm_open.3).
Thanks very much!
Michael
Signature · 9 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html -- 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