diff options
Diffstat (limited to 'man-pages-posix-2017/man3p/mq_open.3p')
| -rw-r--r-- | man-pages-posix-2017/man3p/mq_open.3p | 319 |
1 files changed, 319 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man3p/mq_open.3p b/man-pages-posix-2017/man3p/mq_open.3p new file mode 100644 index 0000000..8b1765d --- /dev/null +++ b/man-pages-posix-2017/man3p/mq_open.3p @@ -0,0 +1,319 @@ +'\" et +.TH MQ_OPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.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 +\(em open a message queue +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include <mqueue.h> +.P +mqd_t mq_open(const char *\fIname\fP, int \fIoflag\fP, ...); +.fi +.SH DESCRIPTION +The +\fImq_open\fR() +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 +.IR 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 +.IR name +argument conforms to the construction rules for a pathname, except that +the interpretation of +<slash> +characters other than the leading +<slash> +character in +.IR name +is implementation-defined, and that the length limits for the +.IR name +argument are implementation-defined and need not be the same as the +pathname limits +{PATH_MAX} +and +{NAME_MAX}. +If +.IR name +begins with the +<slash> +character, then processes calling +\fImq_open\fR() +with the same value of +.IR name +shall refer to the same message queue object, as long as that name +has not been removed. If +.IR name +does not begin with the +<slash> +character, the effect is implementation-defined. If the +.IR name +argument is not the name of an existing message queue and creation is +not requested, +\fImq_open\fR() +shall fail and return an error. +.P +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. +.P +The +.IR oflag +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. +.P +The value of +.IR oflag +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 +.IR oflag : +.IP O_RDONLY 12 +Open the message queue for receiving messages. The process can use the +returned message queue descriptor with +\fImq_receive\fR(), +but not +\fImq_send\fR(). +A message queue may be open multiple times in the same or different +processes for receiving messages. +.IP O_WRONLY 12 +Open the queue for sending messages. The process can use the returned +message queue descriptor with +\fImq_send\fR() +but not +\fImq_receive\fR(). +A message queue may be open multiple times in the same or different +processes for sending messages. +.IP O_RDWR 12 +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. +.P +Any combination of the remaining flags may be specified in the value of +.IR oflag : +.IP O_CREAT 12 +Create a message queue. It requires two additional arguments: +.IR mode , +which shall be of type +.BR mode_t , +and +.IR attr , +which shall be a pointer to an +.BR mq_attr +structure. If the pathname +.IR name +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. The group ID of the message queue shall be +set to the effective group ID of the process; however, if the +.IR name +argument is visible in the file system, the group ID may be set +to the group ID of the containing directory. When bits in +.IR mode +other than the file permission bits are specified, the effect is +unspecified. If +.IR attr +is NULL, the message queue shall be created with implementation-defined +default message queue attributes. If +.IR attr +is non-NULL and the calling process has appropriate privileges on +.IR name , +the message queue +.IR mq_maxmsg +and +.IR mq_msgsize +attributes shall be set to the values of the corresponding members in the +.BR mq_attr +structure referred to by +.IR attr . +The values of the +.IR mq_flags +and +.IR mq_curmsgs +members of the +.BR mq_attr +structure shall be ignored. If +.IR attr +is non-NULL, but the calling process does not have appropriate +privileges on +.IR name , +the +\fImq_open\fR() +function shall fail and return an error without creating the message +queue. +.IP O_EXCL 12 +If O_EXCL and O_CREAT are set, +\fImq_open\fR() +shall fail if the message queue +.IR name +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\fR() +naming the same +.IR name +with O_EXCL and O_CREAT set. If O_EXCL is set and O_CREAT is not set, +the result is undefined. +.IP O_NONBLOCK 12 +Determines whether an +\fImq_send\fR() +or +\fImq_receive\fR() +waits for resources or messages that are not currently available, or +fails with +.IR errno +set to +.BR [EAGAIN] ; +see +.IR "\fImq_send\fR\^(\|)" +and +.IR "\fImq_receive\fR\^(\|)" +for details. +.P +The +\fImq_open\fR() +function does not add or remove messages from the queue. +.SH "RETURN VALUE" +Upon successful completion, the function shall return a message queue +descriptor; otherwise, the function shall return (\fBmqd_t\fP)\-1 +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImq_open\fR() +function shall fail if: +.TP +.BR EACCES +The message queue exists and the permissions specified by +.IR oflag +are denied, or the message queue does not exist and permission to +create the message queue is denied. +.TP +.BR EEXIST +O_CREAT and O_EXCL are set and the named message queue already exists. +.TP +.BR EINTR +The +\fImq_open\fR() +function was interrupted by a signal. +.TP +.BR EINVAL +The +\fImq_open\fR() +function is not supported for the given name. +.TP +.BR EINVAL +O_CREAT was specified in +.IR oflag , +the value of +.IR attr +is not NULL, and either +.IR mq_maxmsg +or +.IR mq_msgsize +was less than or equal to zero. +.TP +.BR EMFILE +Too many message queue descriptors or file descriptors are currently in +use by this process. +.TP +.BR ENFILE +Too many message queues are currently open in the system. +.TP +.BR ENOENT +O_CREAT is not set and the named message queue does not exist. +.TP +.BR ENOSPC +There is insufficient space for the creation of the new message queue. +.br +.P +If any of the following conditions occur, the +\fImq_open\fR() +function may return (\c +.BR mqd_t )\-1 +and set +.IR errno +to the corresponding value. +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR name +argument exceeds +{_POSIX_PATH_MAX} +on systems that do not support the XSI option +or exceeds +{_XOPEN_PATH_MAX} +on XSI systems, +or has a pathname component that is longer than +{_POSIX_NAME_MAX} +on systems that do not support the XSI option +or longer than +{_XOPEN_NAME_MAX} +on XSI systems. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +A future version might require the +\fImq_open\fR() +and +\fImq_unlink\fR() +functions to have semantics similar to normal file system operations. +.SH "SEE ALSO" +.IR "\fImq_close\fR\^(\|)", +.IR "\fImq_getattr\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImq_setattr\fR\^(\|)", +.IR "\fImq_unlink\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<mqueue.h>\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 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 . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |