diff options
Diffstat (limited to 'man-pages-posix-2003/man3p/mq_open.3p')
| -rw-r--r-- | man-pages-posix-2003/man3p/mq_open.3p | 200 |
1 files changed, 200 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man3p/mq_open.3p b/man-pages-posix-2003/man3p/mq_open.3p new file mode 100644 index 0000000..89b7404 --- /dev/null +++ b/man-pages-posix-2003/man3p/mq_open.3p @@ -0,0 +1,200 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MQ_OPEN" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mq_open +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.SH NAME +mq_open \- open a message queue (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include <mqueue.h> +.br +.sp +mqd_t mq_open(const char *\fP\fIname\fP\fB, int\fP \fIoflag\fP\fB, +\&...); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImq_open\fP() function shall establish the connection between +a process and a message queue with a message queue +descriptor. It shall create 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 \fIname\fP 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 \fIname\fP argument shall conform to the +construction rules for a pathname. If \fIname\fP begins with the slash +character, then processes calling \fImq_open\fP() with the +same value of \fIname\fP shall refer to the same message queue object, +as long as that name has not been removed. If \fIname\fP +does not begin with the slash character, the effect is implementation-defined. +The interpretation of slash characters other than +the leading slash character in \fIname\fP is implementation-defined. +If the \fIname\fP argument is not the name of an existing +message queue and creation is not requested, \fImq_open\fP() shall +fail and return an error. +.LP +A message queue descriptor may be implemented using a file descriptor, +in which case applications can open up to at least +{OPEN_MAX} file and message queues. +.LP +The \fIoflag\fP argument requests the desired receive and/or send +access to the message queue. The requested access permission +to receive messages or send messages shall be granted if the calling +process would be granted read or write access, respectively, +to an equivalently protected file. +.LP +The value of \fIoflag\fP is the bitwise-inclusive OR of values from +the following list. Applications shall specify exactly one +of the first three values (access modes) below in the value of \fIoflag\fP: +.TP 7 +O_RDONLY +Open the message queue for receiving messages. The process can use +the returned message queue descriptor with \fImq_receive\fP(), but +not \fImq_send\fP(). A message +queue may be open multiple times in the same or different processes +for receiving messages. +.TP 7 +O_WRONLY +Open the queue for sending messages. The process can use the returned +message queue descriptor with \fImq_send\fP() but not \fImq_receive\fP(). +A message +queue may be open multiple times in the same or different processes +for sending messages. +.TP 7 +O_RDWR +Open the queue for both receiving and sending messages. The process +can use any of the functions allowed for O_RDONLY and +O_WRONLY. A message queue may be open multiple times in the same or +different processes for sending messages. +.sp +.LP +Any combination of the remaining flags may be specified in the value +of \fIoflag\fP: +.TP 7 +O_CREAT +Create a message queue. It requires two additional arguments: \fImode\fP, +which shall be of type \fBmode_t\fP, and +\fIattr\fP, which shall be a pointer to an \fBmq_attr\fP structure. +If the pathname \fIname\fP has already been used to create a +message queue that still exists, then this flag shall have no effect, +except as noted under O_EXCL. Otherwise, a message queue +shall be created without any messages in it. The user ID of the message +queue shall be set to the effective user ID of the process, +and the group ID of the message queue shall be set to the effective +group ID of the process. The file permission bits shall be set +to the value of \fImode\fP. When bits in \fImode\fP other than file +permission bits are set, the effect is +implementation-defined. If \fIattr\fP is NULL, the message queue shall +be created with implementation-defined default message +queue attributes. If \fIattr\fP is non-NULL and the calling process +has the appropriate privilege on \fIname\fP, the message +queue \fImq_maxmsg\fP and \fImq_msgsize\fP attributes shall be set +to the values of the corresponding members in the +\fBmq_attr\fP structure referred to by \fIattr\fP. If \fIattr\fP is +non-NULL, but the calling process does not have the +appropriate privilege on \fIname\fP, the \fImq_open\fP() function +shall fail and return an error without creating the message +queue. +.TP 7 +O_EXCL +If O_EXCL and O_CREAT are set, \fImq_open\fP() shall fail if the message +queue \fIname\fP exists. The check for the existence +of the message queue and the creation of the message queue if it does +not exist shall be atomic with respect to other threads +executing \fImq_open\fP() naming the same \fIname\fP with O_EXCL and +O_CREAT set. If O_EXCL is set and O_CREAT is not set, the +result is undefined. +.TP 7 +O_NONBLOCK +Determines whether an \fImq_send\fP() or \fImq_receive\fP() waits +for resources or messages that are not currently available, or fails +with \fIerrno\fP set to [EAGAIN]; see \fImq_send\fP() and \fImq_receive\fP() +for details. +.sp +.LP +The \fImq_open\fP() function does not add or remove messages from +the queue. +.SH RETURN VALUE +.LP +Upon successful completion, the function shall return a message queue +descriptor; otherwise, the function shall return +(\fBmqd_t\fP)-1 and set \fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fImq_open\fP() function shall fail if: +.TP 7 +.B EACCES +The message queue exists and the permissions specified by \fIoflag\fP +are denied, or the message queue does not exist and +permission to create the message queue is denied. +.TP 7 +.B EEXIST +O_CREAT and O_EXCL are set and the named message queue already exists. +.TP 7 +.B EINTR +The \fImq_open\fP() function was interrupted by a signal. +.TP 7 +.B EINVAL +The \fImq_open\fP() function is not supported for the given name. +.TP 7 +.B EINVAL +O_CREAT was specified in \fIoflag\fP, the value of \fIattr\fP is not +NULL, and either \fImq_maxmsg\fP or \fImq_msgsize\fP +was less than or equal to zero. +.TP 7 +.B EMFILE +Too many message queue descriptors or file descriptors are currently +in use by this process. +.TP 7 +.B ENAMETOOLONG +The length of the \fIname\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENFILE +Too many message queues are currently open in the system. +.TP 7 +.B ENOENT +O_CREAT is not set and the named message queue does not exist. +.TP 7 +.B ENOSPC +There is insufficient space for the creation of the new message queue. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImq_close\fP(), \fImq_getattr\fP(), \fImq_receive\fP(), \fImq_send\fP(), +\fImq_setattr\fP(), \fImq_timedreceive\fP(), \fImq_timedsend\fP(), +\fImq_unlink\fP(), \fImsgctl\fP(), \fImsgget\fP(), \fImsgrcv\fP(), +\fImsgsnd\fP(), the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI<mqueue.h>\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 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 . |