diff options
author | davidxu <davidxu@FreeBSD.org> | 2005-11-30 04:12:37 +0000 |
---|---|---|
committer | davidxu <davidxu@FreeBSD.org> | 2005-11-30 04:12:37 +0000 |
commit | da7f33853459e213d6c82d736324b88e2d5f0e5a (patch) | |
tree | ae6875a0f56c5bb79497f1eb2ebd3c79bad06423 /lib/libc/sys/mq_open.2 | |
parent | 1ecc8e42ea795ea1c6eed93d1135654efb7f9f4e (diff) | |
download | FreeBSD-src-da7f33853459e213d6c82d736324b88e2d5f0e5a.zip FreeBSD-src-da7f33853459e213d6c82d736324b88e2d5f0e5a.tar.gz |
Add manuals for POSIX message queue.
Diffstat (limited to 'lib/libc/sys/mq_open.2')
-rw-r--r-- | lib/libc/sys/mq_open.2 | 278 |
1 files changed, 278 insertions, 0 deletions
diff --git a/lib/libc/sys/mq_open.2 b/lib/libc/sys/mq_open.2 new file mode 100644 index 0000000..d356355 --- /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. |