mq_unlink(3): Add manual page

[fernape]

Summary

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: [e-mail]

PR: 243174

Test Plan

• 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 */

[fernape]

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.

[gbe]

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.

[fernape]

Address comments by gbe@

* Make myself creator
* Mention EACCESS extension
* Mention ENOSYS error code
* Bump .Dd

[yuripv]

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?

[yuripv]

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

[fernape]

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 <[e-mail]>
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 <[e-mail]>
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=176443

So it seems we did ask for permission at some point for the mq pages at a whole.

[yuripv]

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.

[fernape]

Address issues reported by yuripv@

• Remove comment line
• Reword ENOSYS error description

[fernape]

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

[gbe]

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.

[yuripv]

In D28593#643293, @gbe wrote:

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.

No, looks good to me, I was just making sure we got that opengroup notice correctly.

[gbe]

This comment was removed by gbe.

[gbe]

Sorry, was the wrong differential. The Makefile.Inc part is still missing.

[fernape]

Link manpage to the Makefile

spotted by gbe@

[gbe]

In D28593#643325, @fernape wrote:

Link manpage to the Makefile

spotted by gbe@

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.

[fernape]

Move mq_unlink man page to section 2.

Suggested by gbe@

[fernape]

In D28593#643343, @gbe wrote:

In D28593#643325, @fernape wrote:

Link manpage to the Makefile

spotted by gbe@

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.

Yes, sorry. That makes total sense :-)

[gbe]

[fernape]

Thanks!