Add manuals for POSIX message queue.

8 files changed, 1077 insertions, 2 deletions

diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc
index b82e7ed1f36e..26fe4dc603fd 100644
--- a/lib/libc/sys/Makefile.inc
+++ b/lib/libc/sys/Makefile.inc
@@ -70,8 +70,10 @@ MAN+=	_exit.2 accept.2 access.2 acct.2 adjtime.2 \
 	kldunload.2 kqueue.2 kse.2 ktrace.2 link.2 lio_listio.2 listen.2 \
 	lseek.2 \
 	madvise.2 mincore.2 minherit.2 mkdir.2 mkfifo.2 mknod.2 mlock.2 \
-	mlockall.2 mmap.2 modfind.2 modnext.2 modstat.2 mount.2 \
-	mprotect.2 msync.2 munmap.2 nanosleep.2 ntp_adjtime.2 ntp_gettime.2 \
+	mlockall.2 mmap.2 modfind.2 modnext.2 modstat.2 mount.2 mprotect.2 \
+	mq_close.2 mq_getattr.2 mq_notify.2 mq_open.2 mq_receive.2 mq_send.2 \
+	mq_setattr.2 \
+	msync.2 munmap.2 nanosleep.2 ntp_adjtime.2 ntp_gettime.2 \
 	nfssvc.2 open.2 pathconf.2 pipe.2 poll.2 profil.2 ptrace.2 quotactl.2 \
 	read.2 readlink.2 reboot.2 recv.2 rename.2 revoke.2 rfork.2 rmdir.2 \
 	rtprio.2 select.2 semctl.2 semget.2 semop.2 send.2 sendfile.2 \
diff --git a/lib/libc/sys/mq_close.2 b/lib/libc/sys/mq_close.2
new file mode 100644
index 000000000000..cd5e54038940
--- /dev/null
+++ b/lib/libc/sys/mq_close.2
@@ -0,0 +1,87 @@
+.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" 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.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd November 29, 2005
+.Dt MQ_CLOSE 2
+.Os
+.Sh NAME
+.Nm mq_close
+.Nd "close a message queue (REALTIME)"
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In mqueue.h
+.Ft int
+.Fn mq_close "mqd_t mqdes"
+.Sh DESCRIPTION
+The
+.Fn mq_close
+syscall removes the association between the message queue descriptor, 
+.Fa mqdes ,
+and its message queue. The results of using this message queue descriptor
+after successful return from this
+.Fn mq_close ,
+and until the return of this message queue descriptor from a subsequent
+.Fn mq_open ,
+are undefined.
+.Pp
+If the process has successfully attached a notification request to the
+message queue via this
+.Fa mqdes ,
+this attachment will be removed, and the message queue is available for
+another process to attach for notification.
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn mq_close
+syscall returns a value of zero; otherwise, the syscall returns a
+value of -1 and set
+.Va errno
+to indicate the error.
+.Sh ERRORS
+The
+.Fn mq_close
+system call
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EBADF
+The
+.Fa mqdes
+argument is not a valid message queue descriptor.
+.El
+.Sh SEE ALSO
+.Xr mq_open 2 ,
+.Xr mq_unlink 2
+.Sh STANDARDS
+The
+.Fn mq_close
+system call conform to
+.St -p1003.1-2004 .
+.Sh HISTORY
+Support for POSIX message queue first appeared in
+.Fx 7.0 .
diff --git a/lib/libc/sys/mq_getattr.2 b/lib/libc/sys/mq_getattr.2
new file mode 100644
index 000000000000..ac89ea7d11af
--- /dev/null
+++ b/lib/libc/sys/mq_getattr.2
@@ -0,0 +1,107 @@
+.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" 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.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd November 29, 2005
+.Dt MQ_CLOSE 2
+.Os
+.Sh NAME
+.Nm mq_getattr
+.Nd "get message queue attributes (REALTIME)"
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In mqueue.h
+.Ft int
+.Fn mq_getattr "mqd_t mqdes" "struct mq_attr *mqstat"
+.Sh DESCRIPTION
+The
+.Fn mq_getattr
+syscall obtains status information and attributes of the message queue and
+the open message queue description associated with the message queue
+descriptor.
+.Pp
+The
+.Fa mqdes
+argument specifies a message queue descriptor.
+.Pp
+The results are returned in the
+.Vt mq_attr
+structure referenced by the mqstat argument.
+.Pp
+Upon return, the following members will have the values associated with the
+open message queue description as set when the message queue was opened and
+as modified by subsequent
+.Fn mq_setattr
+calls:
+.Va mq_flags.
+.Pp
+The following attributes of the message queue will be returned as set at
+message queue creation:
+.Va mq_maxmsg ,
+.Va mq_msgsize .
+.Pp
+Upon return, the following members within the
+.Vt mq_attr
+structure referenced by the mqstat argument will be set to the current state
+of the message queue:
+.Pp
+.Bl -tag -width Er
+.It Va mq_flags
+The number of messages currently on the queue. 
+.El
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn mq_getattr
+syscall returns zero. Otherwise, the syscall returns -1 and set
+.Va errno
+to indicate the error.
+.Sh ERRORS
+The
+.Fn mq_getattr
+syscall call
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EBADF
+The
+.Fa mqdes
+argument is not a valid message queue descriptor.
+.El
+.Sh SEE ALSO
+.Xr mq_open 2 ,
+.Xr mq_send 2 ,
+.Xr mq_setattr 2 ,
+.Xr mq_timedsend 2 ,
+.Sh STANDARDS
+The
+.Fn mq_getattr
+system call conform to
+.St -p1003.1-2004 .
+.Sh HISTORY
+Support for POSIX message queue first appeared in
+.Fx 7.0 .
diff --git a/lib/libc/sys/mq_notify.2 b/lib/libc/sys/mq_notify.2
new file mode 100644
index 000000000000..304661856147
--- /dev/null
+++ b/lib/libc/sys/mq_notify.2
@@ -0,0 +1,103 @@
+.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" 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.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd November 29, 2005
+.Dt MQ_NOTIFY 2
+.Os
+.Sh NAME
+.Nm mq_notify
+.Nd "notify process that a message is available (REALTIME)"
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In mqueue.h
+.Ft int
+.Fn mq_notify "mqd_t mqdes" "const struct sigevent *notification"
+.Sh DESCRIPTION
+If the argument notification is not
+.Dv NULL ,
+this syscall will register the calling process to be notified of message
+arrival at an empty message queue associated with the specified message
+queue descriptor, 
+.Fa mqdes.
+The notification specified by the notification argument will be sent to
+the process when the message queue transitions from empty to non-empty.
+At any time, only one process may be registered for notification by a
+message queue. If the calling process or any other process has already
+registered for notification of message arrival at the specified message
+queue, subsequent attempts to register for that message queue will fail.
+.Pp
+If notification is
+.Dv NULL
+and the process is currently registered for notification by the specified
+message queue, the existing registration will be removed.
+.Pp
+When the notification is sent to the registered process, its registration
+is removed. The message queue then is available for registration.
+.Pp
+If a process has registered for notification of message arrival at a
+message queue and some thread is blocked in
+.Fn mq_receive
+waiting to receive a message when a message arrives at the queue, the
+arriving message will satisfy the appropriate
+.Fn mq_receive .
+The resulting behavior is as if the message queue remains empty, and no
+notification will be sent.
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn mq_notify
+syscall returns a value of zero; otherwise, the function returns a value
+of -1 and set
+.Va errno
+to indicate the error.
+.Sh ERRORS
+The
+.Fn mq_notify
+syscall call
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EBADF
+The
+.Fa mqdes
+argument is not a valid message queue descriptor.
+.It Bq Er EBUSY
+process is already registered for notification by the message queue.
+.El
+.Sh SEE ALSO
+.Xr mq_open 2 ,
+.Xr mq_send 2 ,
+.Xr mq_timedsend 2
+.Sh STANDARDS
+The
+.Fn mq_notify
+system call conform to
+.St -p1003.1-2004 .
+.Sh HISTORY
+Support for POSIX message queue first appeared in
+.Fx 7.0 .
diff --git a/lib/libc/sys/mq_open.2 b/lib/libc/sys/mq_open.2
new file mode 100644
index 000000000000..d3563555a937
--- /dev/null
+++ b/lib/libc/sys/mq_open.2
@@ -0,0 +1,278 @@
+.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" 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.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd November 29, 2005
+.Dt MQ_OPEN 2
+.Os
+.Sh NAME
+.Nm mq_open 
+.Nd "open a message queue (REALTIME)"
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In mqueue.h
+.Ft mqd_t
+.Fn mq_open "const char *name" "int oflag" "..."
+.Sh DESCRIPTION
+The
+.Fn mq_open
+system call establishs the connection between a process and a message queue
+with a message queue descriptor. It creates an open message queue
+description that refers to the message queue, and a message queue descriptor
+that refers to that open message queue description. The message queue
+descriptor is used by other functions to refer to that message queue. The
+.Fa name
+argument points to a string naming a message queue. It is unspecified
+whether the name appears in the file system and is visible to other functions
+that take pathnames as arguments. The
+.Fa name
+argument conforms to the construction rules for a pathname. If 
+.Fa name
+begins with the slash character, then processes calling
+.Fn mq_open
+with the same value of 
+.Fa name
+refers to the same message queue object, as long as that name has not been
+removed. If
+.Fa name
+does not begin with the slash character, the effect is implementation-defined.
+The interpretation of slash characters other than the leading slash character
+in
+.Fa name
+is implementation-defined. If the
+.Fa name
+argument is not the name of an existing message queue and creation is not
+requested,
+.Fn mq_open
+will fail and returns an error.
+.Pp
+A message queue descriptor may be implemented using a file descriptor, in
+which case applications can open up to at least 
+.Brq Dv OPEN_MAX
+file and message queues.
+.Pp
+The
+.Fa oflag
+argument requests the desired receive and/or send access to the message
+queue. The requested access permission to receive messages or send messages
+would be granted if the calling process would be granted read or write access,
+respectively, to an equivalently protected file.
+.Pp
+The value of
+.Fa oflag
+is the bitwise-inclusive OR of values from the following list.
+Applications should specify exactly one of the first three values (access
+modes) below in the value of
+.Fa oflag :
+.Bl -tag -width Er
+.It Bq Er O_RDONLY
+Open the message queue for receiving messages. The process can use the
+returned message queue descriptor with
+.Fn mq_receive ,
+but not
+.Fn mq_send .
+A message queue may be open multiple times in the same or different processes
+for receiving messages.
+.It Bq Er O_WRONLY
+Open the queue for sending messages. The process can use the returned
+message queue descriptor with
+.Fn mq_send
+but not
+.Fn mq_receive .
+A message queue may be open multiple times in the same or different processes
+for sending messages.
+.It Bq Er O_RDWR
+Open the queue for both receiving and sending messages. The process can use
+any of the functions allowed for
+.Dv O_RDONLY
+and
+.Dv O_WRONLY .
+A message queue may be open multiple times in the same or different processes
+for sending messages.
+.El
+.Pp
+Any combination of the remaining flags may be specified in the value of
+.Fa oflag :
+.Bl -tag -width Er
+.It Bq Er O_CREAT
+Create a message queue. It requires two additional arguments:
+.Fa mode ,
+which is of type
+.Vt mode_t ,
+and
+.Fa attr ,
+which is a pointer to an 
+.Vt mq_attr
+structure. If the pathname
+.Fa name
+has already been used to create a message queue that still exists, then
+this flag has no effect, except as noted under
+.Dv O_EXCL .
+Otherwise, a message queue will be created without any messages
+in it. The user ID of the message queue will be set to the effective user ID
+of the process, and the group ID of the message queue will be set to the
+effective group ID of the process. The permission bits of the message queue
+will be set to the value of the
+.Fa mode
+argument, except those set in the file mode creation mask of the process.
+When bits in
+.Fa mode
+other than the file permission bits are specified, the effect is
+unspecified. If
+.Fa attr
+is
+.Dv NULL ,
+the message queue is created with implementation-defined default message
+queue attributes. If attr is non-NULL and the calling process has the
+appropriate privilege on name, the message queue mq_maxmsg and mq_msgsize
+attributes will be set to the values of the corresponding members in the
+.Vt mq_attr
+structure referred to by
+.Fa attr .
+If
+.Fa attr
+is non-NULL, but the calling process does not have the appropriate privilege
+on name, the
+.Fn mq_open
+function will fail and return an error without creating the message queue.
+.It Bq Er O_EXCL
+If
+.Dv O_EXCL
+and
+.Dv O_CREAT
+are set,
+.Fn mq_open
+will fail if the message queue name exists.
+.It Bq Er O_NONBLOCK
+Determines whether an
+.Fn mq_send
+or
+.Fn mq_receive
+waits for resources or messages that are not currently available, or fails
+with errno set to 
+.Er EAGAIN ;
+see
+.Fn mq_send
+and
+.Fn mq_receive
+for details.
+.Pp
+The
+.Fn mq_open
+function does not add or remove messages from the queue.
+.Sh NOTES
+FreeBSD implements message queue based on file descriptor. The descriptor
+is inherited by child after
+.Fn fork .
+The descriptor is closed in new image after
+.Fn exec .
+.Fn select
+and
+.Fn kevent
+syscalls are supported for message queue descriptor.
+.Sh RETURN VALUES
+Upon successful completion, the function returns a message queue
+descriptor; otherwise, the function returns (mqd_t)-1 and set
+.Va errno
+to indicate the error.
+.Sh ERRORS
+The
+.Fn mq_open
+system call
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EACCES
+The message queue exists and the permissions specified by
+.Fa oflag
+are denied, or the message queue does not exist and permission to create the
+message queue is denied
+.It Bq Er EEXIST
+.Dv O_CREAT
+and
+.Dv O_EXCL
+are set and the named message queue already exists.
+.It Bq Er EINTR
+The
+.Fn mq_open
+function was interrupted by a signal.
+.It Bq Er EINVAL
+The
+.Fn mq_open
+function is not supported for the given name.
+.It Bq Er EINVAL
+.Dv O_CREAT
+was specified in
+.Fa oflag ,
+the value of attr is not
+.Dv NULL ,
+and either
+.Va mq_maxmsg
+or
+.Va mq_msgsize
+was less than or equal to zero.
+.It Bq Er EMFILE
+Too many message queue descriptors or file descriptors are currently in use
+by this process.
+.It Bq Er ENAMETOOLONG
+The length of the name argument exceeds
+.Brq Dv PATH_MAX
+or a pathname component
+is longer than
+.Brq Dv NAME_MAX .
+.It Bq Er ENFILE
+Too many message queues are currently open in the system.
+.It Bq Er ENOENT
+.Dv O_CREAT
+is not set and the named message queue does not exist.
+.It Bq Er ENOSPC
+There is insufficient space for the creation of the new message queue.
+.El
+.Sh SEE ALSO
+.Xr mq_close 2 ,
+.Xr mq_getattr 2 ,
+.Xr mq_receive 2 ,
+.Xr mq_send 2 ,
+.Xr mq_setattr 2 ,
+.Xr mq_timedreceive 3 ,
+.Xr mq_timedsend 3
+.Xr mq_unlink 3
+.Sh STANDARDS
+The
+.Fn mq_open
+system call conform to
+.St -p1003.1-2004 .
+.Sh HISTORY
+Support for POSIX message queue first appeared in
+.Fx 7.0 .
+.Sh BUGS
+This implementation places strict requirements on the value of
+.Fa name :
+it must begin with a slash
+.Pq Ql / ,
+contain no other slash characters.
diff --git a/lib/libc/sys/mq_receive.2 b/lib/libc/sys/mq_receive.2
new file mode 100644
index 000000000000..4db69b89571e
--- /dev/null
+++ b/lib/libc/sys/mq_receive.2
@@ -0,0 +1,190 @@
+.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" 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.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd November 29, 2005
+.Dt MQ_SEND 2
+.Os
+.Sh NAME
+.Nm mq_receive , mq_timedreceive
+.Nd "receive a message from message queue (REALTIME)"
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In mqueue.h
+.Ft ssize_t
+.Fo mq_receive
+.Fa "mqd_t mqdes"
+.Fa "char *msg_ptr"
+.Fa "size_t msg_len"
+.Fa "unsigned *msg_prio"
+.Fc
+.Ft ssize_t
+.Fo mq_timereceive
+.Fa "mqd_t mqdes"
+.Fa "char *msg_ptr"
+.Fa "size_t msg_len"
+.Fa "unsigned *msg_prio"
+.Fa "const struct timespec *abs_timeout"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn mq_receive
+syscall receives oldest of the highest priority message(s) from the
+message queue specified by
+.Fa mqdes .
+If the size of the buffer in bytes, specified by the
+.Fa msg_len
+argument, is less than the
+.Fa mq_msgsize
+attribute of the message queue, the syscall will fail and return an
+error. Otherwise, the selected message will be removed from the queue
+and copied to the buffer pointed to by the
+.Fa msg_ptr
+argument.
+.Pp
+If the value of 
+.Fa msg_len
+is greater than
+.Brq Dv SSIZE_MAX ,
+the result is implementation-defined.
+.Pp
+If the argument
+.Fa msg_prio
+is not NULL, the priority of the selected message will be stored in the
+location referenced by
+.Fa msg_prio .
+If the specified message queue is empty and
+.Dv O_NONBLOCK
+is not set in the message queue description associated with
+.Fa mqdes ,
+.Fn mq_receive
+will block until a message is enqueued on the message queue or until
+.Fn mq_receive
+is interrupted by a signal. If more than one thread is waiting to receive
+a message when a message arrives at an empty queue and the Priority
+Scheduling option is supported, then the thread of highest priority that
+has been waiting the longest will be selected to receive the message.
+Otherwise, it is unspecified which waiting thread receives the message.
+If the specified message queue is empty and
+.Dv O_NONBLOCK
+is set in the message queue description associated with mqdes, no message
+will be removed from the queue, and
+.Fn mq_receive
+will return an error.
+.Pp
+The
+.Fn mq_timedreceive
+syscall will receive the oldest of the highest priority messages from the
+message queue specified by
+.Fa mqdes
+as described for the
+.Fn mq_receive
+syscall. However, if
+.Dv O_NONBLOCK
+was not specified when the message queue was opened via the
+.Fn mq_open
+syscall, and no message exists on the queue to satisfy the receive, the wait
+for such a message will be terminated when the specified timeout expires. If
+.Dv O_NONBLOCK
+is set, this syscall is equivalent to
+.Fn mq_receive .
+.Pp
+The timeout expires when the absolute time specified by
+.Fa abs_timeout
+passes, as measured by the clock on which timeouts are based (that is, when
+the value of that clock equals or exceeds
+.Fa abs_timeout ) ,
+or if the absolute time specified by
+.Fa abs_timeout
+has already been passed at the time of the call.
+.Pp
+The timeout is based on the CLOCK_REALTIME clock.
+.Pp
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn mq_receive
+and
+.Fn mq_timedreceive
+syscalls return the length of the selected message in bytes and the
+message is removed from the queue. Otherwise, no message is removed
+from the queue, the syscalls returns a value of -1, and set
+.Va errno
+to indicate the error.
+.Sh ERRORS
+The
+.Fn mq_receive
+and
+.Fn mq_timedreceive
+system calls
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EAGAIN
+.Dv O_NONBLOCK
+flag is set in the message queue description associated with
+.Fa mqdes ,
+and the specified message queue is empty.
+.It Bq Er EBADF
+The
+.Fa mqdes
+argument is not a valid message queue descriptor open for reading.
+.It Bq Er EMSGSIZE
+The specified message buffer size,
+.Fa msg_len ,
+is less than the message size attribute of the message queue.
+.It Bq Er EINTR
+The
+.Fn mq_receive
+or
+.Fn mq_timedreceive
+operation was interrupted by a signal.
+.It Bq Er EINVAL
+The process or thread would have blocked, and the
+.Fa abs_timeout
+parameter specified a nanoseconds field value less than zero or greater
+than or equal to 1000 million.
+.It Bq Er ETIMEDOUT
+The
+.Dv O_NONBLOCK
+flag was not set when the message queue was opened, but no message arrived
+on the queue before the specified timeout expired.
+.El
+.Sh SEE ALSO
+.Xr mq_open 2 ,
+.Xr mq_send 2 ,
+.Xr mq_timesend 2
+.Sh STANDARDS
+The
+.Fn mq_receive
+and
+.Fn mq_timereceive
+system calls conform to
+.St -p1003.1-2004 .
+.Sh HISTORY
+Support for POSIX message queue first appeared in
+.Fx 7.0 .
diff --git a/lib/libc/sys/mq_send.2 b/lib/libc/sys/mq_send.2
new file mode 100644
index 000000000000..26b1504a4710
--- /dev/null
+++ b/lib/libc/sys/mq_send.2
@@ -0,0 +1,204 @@
+.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" 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.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd November 29, 2005
+.Dt MQ_SEND 2
+.Os
+.Sh NAME
+.Nm mq_send , mq_timedsend
+.Nd "send a message to message queue (REALTIME)"
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In mqueue.h
+.Ft int
+.Fo mq_send
+.Fa "mqd_t mqdes"
+.Fa "const char *msg_ptr"
+.Fa "size_t msg_len"
+.Fa "unsigned msg_prio"
+.Fc
+.Ft int
+.Fo mq_timesend
+.Fa "mqd_t mqdes"
+.Fa "const char *msg_ptr"
+.Fa "size_t msg_len"
+.Fa "unsigned msg_prio"
+.Fa "const struct timespec *abs_timeout"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn mq_send
+syscall adds the message pointed to by the argument
+.Fa msg_ptr
+to the message queue specified by
+.Fa mqdes .
+The 
+.Fa msg_len
+argument specifies the length of the message, in bytes, pointed to by
+.Fa msg_ptr .
+The value of
+.Fa msg_len
+should be less than or equal to the
+.Fa mq_msgsize
+attribute of the message queue, or
+.Fn mq_send
+will fail.
+.Pp
+If the specified message queue is not full,
+.Fn mq_send
+will behave as if the message is inserted into the message queue at
+the position indicated by the
+.Fa msg_prio
+argument. A message with a larger numeric value of
+.Fa msg_prio
+will be inserted before messages with lower values of
+.Fa msg_prio .
+A message will be inserted after other messages in the queue, if any,
+with equal
+.Fa msg_prio .
+The value of
+.Fa msg_prio
+should be less than
+.Brq Dv MQ_PRIO_MAX .
+.Pp
+If the specified message queue is full and
+.Dv O_NONBLOCK
+is not set in the message queue description associated with
+.Fa mqdes ,
+.Fn mq_send
+will block until space becomes available to enqueue the
+message, or until
+.Fn mq_send
+is interrupted by a signal. If more than one thread is
+waiting to send when space becomes available in the message queue and
+the Priority Scheduling option is supported, then the thread of the
+highest priority that has been waiting the longest will be unblocked
+to send its message. Otherwise, it is unspecified which waiting thread
+is unblocked. If the specified message queue is full and
+.Dv O_NONBLOCK
+is set in the message queue description associated with
+.Fa mqdes ,
+the message will not be queued and
+.Fn mq_send
+will return an error.
+.Pp
+The
+.Fn mq_timedsend
+syscall will add a message to the message queue specified by
+.Fa mqdes
+in the manner defined for the
+.Fn mq_send
+syscall. However, if the specified message queue is full and
+.Dv O_NONBLOCK
+is not set in the message queue description associated with
+.Fa mqdes ,
+the wait for sufficient room in the queue will be terminated when
+the specified timeout expires. If
+.Dv O_NONBLOCK
+is set in the message queue description, this syscall is
+equivalent to
+.Fn mq_send .
+.Pp
+The timeout will expire when the absolute time specified by
+.Fa abs_timeout
+passes, as measured by the clock on which timeouts are based (that is,
+when the value of that clock equals or exceeds 
+.Fa abs_timeout ) ,
+or if the absolute time specified by
+.Fa abs_timeout
+has already been passed at the time of the call.
+.Pp
+The timeout is based on the CLOCK_REALTIME clock.
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn mq_send
+and
+.Fn mq_timedsend
+syscalls return a value of zero. Otherwise, no message will be
+enqueued, the syscalls returns -1, and
+.Va errno
+is set to indicate the error.
+.Sh ERRORS
+The
+.Fn mq_send
+and
+.Fn mq_timedsend
+system calls
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EAGAIN
+The
+.Dv O_NONBLOCK
+flag is set in the message queue description associated with
+.Fa mqdes ,
+and the specified message queue is full.
+.It Bq Er EBADF
+The
+.Fa mqdes
+argument is not a valid message queue descriptor open for writing.
+.It Bq Er EINTR
+A signal interrupted the call to
+.Fn mq_send
+or
+.Fn mq_timedsend. 
+.It Bq Er EINVAL
+The value of
+.Fa msg_prio
+was outside the valid range.
+.It Bq Er EINVAL
+The process or thread would have blocked, and the
+.Fa abs_timeout
+parameter specified a nanoseconds field value less than zero or greater
+than or equal to 1000 million.
+.It Bq Er EMSGSIZE
+The specified message length,
+.Fa msg_len ,
+exceeds the message size attribute of the message queue.
+.It Bq Er ETIMEDOUT
+The
+.Dv O_NONBLOCK
+flag was not set when the message queue was opened, but the timeout
+expired before the message could be added to the queue.
+.El
+.Sh SEE ALSO
+.Xr mq_open 2 ,
+.Xr mq_receive 2 ,
+.Xr mq_setattr 2 ,
+.Xr mq_timereceive 2
+.Sh STANDARDS
+The
+.Fn mq_send
+and
+.Fn mq_timesend
+system calls conform to
+.St -p1003.1-2004 .
+.Sh HISTORY
+Support for POSIX message queue first appeared in
+.Fx 7.0 .
diff --git a/lib/libc/sys/mq_setattr.2 b/lib/libc/sys/mq_setattr.2
new file mode 100644
index 000000000000..0e6781271983
--- /dev/null
+++ b/lib/libc/sys/mq_setattr.2
@@ -0,0 +1,104 @@
+.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" 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.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd November 29, 2005
+.Dt MQ_CLOSE 2
+.Os
+.Sh NAME
+.Nm mq_setattr
+.Nd "set message queue attributes (REALTIME)"
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In mqueue.h
+.Ft int
+.Fo mq_setattr
+.Fa "mqd_t mqdes"
+.Fa "struct mq_attr *restrict mqstat"
+.Fa "struct mq_attr *restrict omqstat"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn mq_setattr
+syscall sets attributes associated with the open message queue description
+referenced by the message queue descriptor specified by
+.Fa mqdes .
+The message queue attributes corresponding to the following members defined
+in the
+.Vt mq_attr
+structure will be set to the specified values upon successful completion of
+.Fn mq_setattr :
+.Pp
+.Bl -tag -width Er
+.It Va mq_flags
+The value of this member is the bitwise-logical OR of zero or more of
+.Dv O_NONBLOCK
+and any implementation-defined flags.
+.El
+.Pp
+The values of the
+.Va mq_maxmsg ,
+.Va mq_msgsize ,
+and
+.Va mq_curmsgs
+embers of the
+.Vt mq_attr
+structure are ignored by
+.Fn mq_setattr .
+.Sh RETURN VALUES
+Upon successful completion, the function returns a value of zero and the
+attributes of the message queue will have been changed as specified.
+.Pp
+Otherwise, the message queue attributes are unchanged, and the function
+returns a value of -1 and set 
+.Va errno
+to indicate the error.
+.Sh ERRORS
+The
+.Fn mq_setattr
+syscall call
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EBADF
+The
+.Fa mqdes
+argument is not a valid message queue descriptor.
+.El
+.Sh SEE ALSO
+.Xr mq_open 2 ,
+.Xr mq_send 2 ,
+.Xr mq_timedsend 2 ,
+.Sh STANDARDS
+The
+.Fn mq_setattr
+system call conform to
+.St -p1003.1-2004 .
+.Sh HISTORY
+Support for POSIX message queue first appeared in
+.Fx 7.0 .