Differential D28593 Diff 83912 lib/libc/sys/mq_unlink.3

Changeset View

Standalone View

lib/libc/sys/mq_unlink.3

This file was added.

				.\" Copyright (c) 2021 Fernando Apesteguia <fernape@FreeBSD.org>
				.\" All rights reserved.
				gbeUnsubmitted Done Inline Actions This Copyright statement should be updated to reflect that you wrote this manual page. gbe: This Copyright statement should be updated to reflect that you wrote this manual page.
				yuripvUnsubmitted Done Inline Actions As mentioned previously a lot, this does not provide any value anymore. yuripv: As mentioned previously a lot, this does not provide any value anymore.
				.\"
				.\" Redistribution and use in source and binary forms, with or without
				.\" modification, are permitted provided that the following conditions
				.\" are met:
				.\" 1. Redistributions of source code must retain the above copyright
				.\" notice(s), this list of conditions and the following disclaimer as
				.\" the first lines of this file unmodified other than the possible
				.\" addition of one or more copyright notices.
				.\" 2. Redistributions in binary form must reproduce the above copyright
				.\" notice(s), this list of conditions and the following disclaimer in
				.\" the documentation and/or other materials provided with the
				.\" distribution.
				.\"
				.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
				.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
				.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
				.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
				.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
				.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
				.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
				.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
				.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
				.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
				.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
				.\"
				.\" Portions of this text are reprinted and reproduced in electronic form
				.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology --
				.\" Portable Operating System Interface (POSIX), The Open Group Base
				.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
				.\" Electrical and Electronics Engineers, Inc and The Open Group. In the
				.\" event of any discrepancy between this version and the original IEEE and
				.\" The Open Group Standard, the original IEEE and The Open Group Standard is
				.\" the referee document. The original Standard can be obtained online at
				.\" http://www.opengroup.org/unix/online.html.
				.\"
				.\" $FreeBSD$
				.\"
				.Dd February 15, 2021
				.Dt MQ_UNLINK 3
				gbeUnsubmitted Done Inline Actions Should be bumped. gbe: Should be bumped.
				.Os
				.Sh NAME
				.Nm mq_unlink
				.Nd "mq_unlink - remove a message queue (REALTIME)"
				.Sh LIBRARY
				.Lb librt
				.Sh SYNOPSIS
				.In mqueue.h
				.Ft int
				.Fn mq_unlink "const char *name"
				.Sh DESCRIPTION
				The
				.Fn mq_unlink
				function removes the message queue named by the string
				.Fa name .
				If one or more processes have the message queue open when
				.Fn mq_unlink
				is called, destruction of the message queue will be postponed
				until all references to the message queue have been closed.
				However, the
				.Fn mq_unlink
				call need not block until all references have been closed; it may return
				immediately.
				.Pp
				After a successful call to
				.Fn mq_unlink ,
				reuse of the name will subsequently cause
				.Xr mq_open 2
				to behave as if no message queue of this name exists.
				.Sh RETURN VALUES
				.Rv -std
				.Sh ERRORS
				The
				.Fn mq_unlink
				system call
				will fail if:
				.Bl -tag -width Er
				.It Bq Er EACCESS
				Permission is denied to unlink the message queue represented by
				.Fa name .
				.It Bq Er EINVAL
				.Fa name
				is invalid.
				.It Bq Er ENAMETOOLONG
				The length of the
				.Fa name
				argument exceeds
				.Brq Dv PATH_MAX
				or
				a pathname component is longer than
				.Brq Dv NAME_MAX .
				.It Bq Er ENOENT
				The message queue does not exist.
				.It Bq Er ENOSYS
				.Xr mqueuefs 5
				fernapeAuthorUnsubmitted Done Inline Actions Should we include ENOSYS? That is the error we get if `mqueuefs(5)` is not loaded or included in the kernel. fernape: Should we include ENOSYS? That is the error we get if `mqueuefs(5)` is not loaded or included…
				gbeUnsubmitted Done Inline Actions I would include ENOSYS. gbe: I would include ENOSYS.
				module is not loaded or included in the kernel.
				yuripvUnsubmitted Done Inline Actions I find this a bit confusing, does it mean `not loaded and not included in the kernel`? yuripv: I find this a bit confusing, does it mean `not loaded and not included in the kernel`?
				fernapeAuthorUnsubmitted Done Inline Actions Maybe "is neither loaded nor included in the kernel" sounds better? fernape: Maybe //"is neither loaded nor included in the kernel"// sounds better?
				.El
				.Sh SEE ALSO
				.Xr mq_open 2
				.Sh STANDARDS
				The
				.Fn mq_unlink
				fernapeAuthorUnsubmitted Done Inline Actions 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. fernape: I am not 100% sure about this since we might return `EINVAL` and it is not mentioned by [[https…
				gbeUnsubmitted Done Inline Actions Thats okay, you may mention that the EINVAL error is an extension to the POSIX specification. gbe: Thats okay, you may mention that the EINVAL error is an extension to the POSIX specification.
				system call conforms to
				.St -p1003.1-2004 .
				The
				.Bq Er EACCESS
				error code is an extension to the standard.
				.Sh HISTORY
				fernapeAuthorUnsubmitted Done Inline Actions Here is a warning for the double dash. fernape: Here is a warning for the double dash.
				Support for POSIX message queues first appeared in
				.Fx 7.0 .
				.Sh COPYRIGHT
				yuripvUnsubmitted Not Done Inline Actions 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: I think you should include it as part of commented copyright section above, as was done in e.
				yuripvUnsubmitted Not Done Inline Actions 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 yuripv: As an example of the man page using opengroup text: http://src.illumos.org/source/xref/illumos…
				fernapeAuthorUnsubmitted Done Inline Actions 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=176443 So it seems we did ask for permission at some point for the `mq` pages at a whole. fernape: Well, in the URL, there is this text: //The Institute of Electrical and Electronics Engineers…
				yuripvUnsubmitted Not Done Inline Actions 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. yuripv: Great, thanks for clarifying this. I'd still include it the copyright header above as readers…
				fernapeAuthorUnsubmitted Done Inline Actions 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 fernape:* Hummm... the COPYRIGHT notice is also at the end of the commentary in the beginning of the file.
				Portions of this text are reprinted and reproduced in electronic form
				from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology --
				Portable Operating System Interface (POSIX), The Open Group Base
				Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
				Electrical and Electronics Engineers, Inc and The Open Group.
				In the event of any discrepancy between this version and the original IEEE and
				The Open Group Standard, the original IEEE and The Open Group Standard is
				the referee document.
				The original Standard can be obtained online at
				http://www.opengroup.org/unix/online.html.