diff options
author | David Xu <davidxu@FreeBSD.org> | 2005-11-30 04:12:37 +0000 |
---|---|---|
committer | David Xu <davidxu@FreeBSD.org> | 2005-11-30 04:12:37 +0000 |
commit | 968cc4bd6123918c514b47d0083b9cc6c1236043 (patch) | |
tree | ae6875a0f56c5bb79497f1eb2ebd3c79bad06423 /lib/libc | |
parent | 8d984020408ce32c7e49da708cb3bf6ae419a934 (diff) | |
download | src-968cc4bd6123918c514b47d0083b9cc6c1236043.tar.gz src-968cc4bd6123918c514b47d0083b9cc6c1236043.zip |
Add manuals for POSIX message queue.
Notes
Notes:
svn path=/head/; revision=152942
Diffstat (limited to 'lib/libc')
-rw-r--r-- | lib/libc/sys/Makefile.inc | 6 | ||||
-rw-r--r-- | lib/libc/sys/mq_close.2 | 87 | ||||
-rw-r--r-- | lib/libc/sys/mq_getattr.2 | 107 | ||||
-rw-r--r-- | lib/libc/sys/mq_notify.2 | 103 | ||||
-rw-r--r-- | lib/libc/sys/mq_open.2 | 278 | ||||
-rw-r--r-- | lib/libc/sys/mq_receive.2 | 190 | ||||
-rw-r--r-- | lib/libc/sys/mq_send.2 | 204 | ||||
-rw-r--r-- | lib/libc/sys/mq_setattr.2 | 104 |
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 . |