Add a succint manual page for mq_unlink
Mostly borrowed from https://pubs.opengroup.org/onlinepubs/9699959099/ and
hence, the disclaimer note at the bottom.
PR: 243174
Submitted by:
Reported by: rfg-freebsd@tristatelogic.com
PR: 243174
Details
Details
- Reviewers
0mp gbe yuripv - Group Reviewers
manpages - Commits
- rGacab1d58befa: mq_unlink(3): Add manual page
- mandoc -T lint OK (warning about --)
- igor OK
- man page renders properly
This small program can help to verify error codes:
#include <errno.h>
#include <mqueue.h>
#include <stdio.h>
#include <string.h>
int
main(int argc, char **argv)
{
const char *long_name = "/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
int ret;
/* This name does not exist*/
ret = mq_unlink("/thisdoesnotexist");
printf("mq_unlink returned: %d with errno = %d and message '%s'\n", ret
, errno, strerror(errno));
/* This name is too long */
ret = mq_unlink(long_name);
printf("mq_unlink returned: %d with errno = %d and message '%s'\n", ret
, errno, strerror(errno));
/* This name does not look like a path */
ret = mq_unlink("aaa");
printf("mq_unlink returned: %d with errno = %d and message '%s'\n", ret
, errno, strerror(errno));
return (0);
}Without module loaded mq_unlink returned: -1 with errno = 78 and message 'Function not implemented' /* Absurd name */ mq_unlink returned: -1 with errno = 2 and message 'No such file or directory' /* Terribly long name*/ mq_unlink returned: -1 with errno = 63 and message 'File name too long' /* This does not start with slash */ mq_unlink returned: -1 with errno = 22 and message 'Invalid argument' $ egrep -w 'ENOENT|EINVAL|ENAMETOOLONG|ENOSYS' /usr/include/errno.h #define ENOENT 2 /* No such file or directory */ #define EINVAL 22 /* Invalid argument */ #define ENAMETOOLONG 63 /* File name too long */ #define ENOSYS 78 /* Function not implemented */
Diff Detail
Diff Detail
- Repository
- rG FreeBSD src repository
- Lint
Lint Not Applicable - Unit
Tests Not Applicable
Event Timeline
| lib/libc/sys/mq_unlink.3 | ||
|---|---|---|
| 95 ↗ | (On Diff #83702) | Should we include ENOSYS? That is the error we get if mqueuefs(5) is not loaded or included in the kernel. |
| 102 ↗ | (On Diff #83702) | I am not 100% sure about this since we might return EINVAL and it is not mentioned by POSIX IEEE Std 1003.1, 2004 Edition. Other mq_* man pages claim to be POSIX compliant though. |
| 108 ↗ | (On Diff #83702) | Here is a warning for the double dash. |
Comment Actions
Good work. Some inline comments and you have to update Makefile.inc to actual install the man page.
| lib/libc/sys/mq_unlink.3 | ||
|---|---|---|
| 1 ↗ | (On Diff #83702) | This Copyright statement should be updated to reflect that you wrote this manual page. |
| 40 ↗ | (On Diff #83702) | Should be bumped. |
| 95 ↗ | (On Diff #83702) | I would include ENOSYS. |
| 102 ↗ | (On Diff #83702) | Thats okay, you may mention that the EINVAL error is an extension to the POSIX specification. |
Comment Actions
Address comments by gbe@ * Make myself creator * Mention EACCESS extension * Mention ENOSYS error code * Bump .Dd
| lib/libc/sys/mq_unlink.3 | ||
|---|---|---|
| 2 ↗ | (On Diff #83912) | As mentioned previously a lot, this does not provide any value anymore. |
| 97 ↗ | (On Diff #83912) | I find this a bit confusing, does it mean not loaded and not included in the kernel? |
| 112 ↗ | (On Diff #83912) | I think you should include it as part of *commented* copyright section above, as was done in e.g. solaris man pages. I should note though that those include the following text: .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for .\" permission to reproduce portions of its copyrighted documentation. .\" Original documentation from The Open Group can be obtained online at .\" http://www.opengroup.org/bookstore/. Not sure if we need some kind of permission to copy? |
| lib/libc/sys/mq_unlink.3 | ||
|---|---|---|
| 112 ↗ | (On Diff #83912) | As an example of the man page using opengroup text: http://src.illumos.org/source/xref/illumos-gate/usr/src/man/man5/regex.5?r=0d54f452 |
| lib/libc/sys/mq_unlink.3 | ||
|---|---|---|
| 97 ↗ | (On Diff #83912) | Maybe "is neither loaded nor included in the kernel" sounds better? |
| 112 ↗ | (On Diff #83912) | Well, in the URL, there is this text: The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation I did not ask for permission, that is for sure. The note I copied verbatim comes from mq_close.2. Having a look at the changes I see the following: commit db47316b5cc4d4a3a6509ba4f14f439fb365f010
Author: Philip Paeps <philip@FreeBSD.org>
Date: Fri Feb 29 17:48:25 2008 +0000
Use the easily-greppable copyright notice template from
src/share/examples/mdoc/POSIX-copyright.
Requested by: ru
Notes:
svn path=/head/; revision=176661
commit a975b4b6f22e2cd719ae19fcf264a80857a049ea
Author: Philip Paeps <philip@FreeBSD.org>
Date: Thu Feb 21 19:16:57 2008 +0000
Note, as required by our agreement with IEEE/The Open Group, that the message
queue manual pages excerpt the POSIX standard.
Spotted by: Mindaugas Rasiukevicius <rmind -at- NetBSD.org>
Reviewed by: imp
MFC after: 1 day
Notes:
svn path=/head/; revision=176443So it seems we did ask for permission at some point for the mq pages at a whole. |
| lib/libc/sys/mq_unlink.3 | ||
|---|---|---|
| 112 ↗ | (On Diff #83912) | Great, thanks for clarifying this. I'd still include it the copyright header above as readers are not really interested in documentation copyrights, and we still have it in "binary" form. |
Comment Actions
Address issues reported by yuripv@
- Remove comment line
- Reword ENOSYS error description
| lib/libc/sys/mq_unlink.3 | ||
|---|---|---|
| 112 ↗ | (On Diff #83912) | Hummm... the COPYRIGHT notice is also at the end of the commentary in the beginning of the file... or are you referring to something else? We could remove the COPYRIGHT section, although it seems to be there for the rest of mq_* manpages |
Comment Actions
There is still the Makefile change missing.
@yuripv do you have any open issues for the man page?
I would approve it, but you have spend more time in reviewing it.
Comment Actions
No, looks good to me, I was just making sure we got that opengroup notice correctly.
This comment was removed by gbe.
Comment Actions
Thanks for the change. Since the other mq_* man pages are in section 2, would your rename the man page and update the Makefile again.