diff options
Diffstat (limited to 'man3/mq_open.3')
| -rw-r--r-- | man3/mq_open.3 | 299 |
1 files changed, 299 insertions, 0 deletions
diff --git a/man3/mq_open.3 b/man3/mq_open.3 new file mode 100644 index 0000000..32ff069 --- /dev/null +++ b/man3/mq_open.3 @@ -0,0 +1,299 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mq_open 3 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +mq_open \- open a message queue +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.BR "#include <fcntl.h>" " /* For O_* constants */" +.BR "#include <sys/stat.h>" " /* For mode constants */" +.B #include <mqueue.h> +.PP +.BI "mqd_t mq_open(const char *" name ", int " oflag ); +.BI "mqd_t mq_open(const char *" name ", int " oflag ", mode_t " mode , +.BI " struct mq_attr *" attr ); +.fi +.SH DESCRIPTION +.BR mq_open () +creates a new POSIX message queue or opens an existing queue. +The queue is identified by +.IR name . +For details of the construction of +.IR name , +see +.BR mq_overview (7). +.PP +The +.I oflag +argument specifies flags that control the operation of the call. +(Definitions of the flags values can be obtained by including +.IR <fcntl.h> .) +Exactly one of the following must be specified in +.IR oflag : +.TP +.B O_RDONLY +Open the queue to receive messages only. +.TP +.B O_WRONLY +Open the queue to send messages only. +.TP +.B O_RDWR +Open the queue to both send and receive messages. +.PP +Zero or more of the following flags can additionally be +.IR OR ed +in +.IR oflag : +.TP +.BR O_CLOEXEC " (since Linux 2.6.26)" +.\" commit 269f21344b23e552c21c9e2d7ca258479dcd7a0a +Set the close-on-exec flag for the message queue descriptor. +See +.BR open (2) +for a discussion of why this flag is useful. +.TP +.B O_CREAT +Create the message queue if it does not exist. +The owner (user ID) of the message queue is set to the effective +user ID of the calling process. +The group ownership (group ID) is set to the effective group ID +of the calling process. +.\" In reality the filesystem IDs are used on Linux. +.TP +.B O_EXCL +If +.B O_CREAT +was specified in +.IR oflag , +and a queue with the given +.I name +already exists, then fail with the error +.BR EEXIST . +.TP +.B O_NONBLOCK +Open the queue in nonblocking mode. +In circumstances where +.BR mq_receive (3) +and +.BR mq_send (3) +would normally block, these functions instead fail with the error +.BR EAGAIN . +.PP +If +.B O_CREAT +is specified in +.IR oflag , +then two additional arguments must be supplied. +The +.I mode +argument specifies the permissions to be placed on the new queue, +as for +.BR open (2). +(Symbolic definitions for the permissions bits can be obtained by including +.IR <sys/stat.h> .) +The permissions settings are masked against the process umask. +.PP +The fields of the +.I struct mq_attr +pointed to +.I attr +specify the maximum number of messages and +the maximum size of messages that the queue will allow. +This structure is defined as follows: +.PP +.in +4n +.EX +struct mq_attr { + long mq_flags; /* Flags (ignored for mq_open()) */ + long mq_maxmsg; /* Max. # of messages on queue */ + long mq_msgsize; /* Max. message size (bytes) */ + long mq_curmsgs; /* # of messages currently in queue + (ignored for mq_open()) */ +}; +.EE +.in +.PP +Only the +.I mq_maxmsg +and +.I mq_msgsize +fields are employed when calling +.BR mq_open (); +the values in the remaining fields are ignored. +.PP +If +.I attr +is NULL, then the queue is created with implementation-defined +default attributes. +Since Linux 3.5, two +.I /proc +files can be used to control these defaults; see +.BR mq_overview (7) +for details. +.SH RETURN VALUE +On success, +.BR mq_open () +returns a message queue descriptor for use by other +message queue functions. +On error, +.BR mq_open () +returns +.IR "(mqd_t)\ \-1", +with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The queue exists, but the caller does not have permission to +open it in the specified mode. +.TP +.B EACCES +.I name +contained more than one slash. +.\" Note that this isn't consistent with the same case for sem_open() +.TP +.B EEXIST +Both +.B O_CREAT +and +.B O_EXCL +were specified in +.IR oflag , +but a queue with this +.I name +already exists. +.TP +.B EINVAL +.\" glibc checks whether the name starts with a "/" and if not, +.\" gives this error +.I name +doesn't follow the format in +.BR mq_overview (7). +.TP +.B EINVAL +.B O_CREAT +was specified in +.IR oflag , +and +.I attr +was not NULL, but +.I attr\->mq_maxmsg +or +.I attr\->mq_msqsize +was invalid. +Both of these fields must be greater than zero. +In a process that is unprivileged (does not have the +.B CAP_SYS_RESOURCE +capability), +.I attr\->mq_maxmsg +must be less than or equal to the +.I msg_max +limit, and +.I attr\->mq_msgsize +must be less than or equal to the +.I msgsize_max +limit. +In addition, even in a privileged process, +.I attr\->mq_maxmsg +cannot exceed the +.B HARD_MAX +limit. +(See +.BR mq_overview (7) +for details of these limits.) +.TP +.B EMFILE +The per-process limit on the number of open file +and message queue descriptors has been reached +(see the description of +.B RLIMIT_NOFILE +in +.BR getrlimit (2)). +.TP +.B ENAMETOOLONG +.I name +was too long. +.TP +.B ENFILE +The system-wide limit on the total number of open files +and message queues has been reached. +.TP +.B ENOENT +The +.B O_CREAT +flag was not specified in +.IR oflag , +and no queue with this +.I name +exists. +.TP +.B ENOENT +.I name +was just "/" followed by no other characters. +.\" Note that this isn't consistent with the same case for sem_open() +.TP +.B ENOMEM +Insufficient memory. +.TP +.B ENOSPC +Insufficient space for the creation of a new message queue. +This probably occurred because the +.I queues_max +limit was encountered; see +.BR mq_overview (7). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mq_open () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH VERSIONS +.SS C library/kernel differences +The +.BR mq_open () +library function is implemented on top of a system call of the same name. +The library function performs the check that the +.I name +starts with a slash (/), giving the +.B EINVAL +error if it does not. +The kernel system call expects +.I name +to contain no preceding slash, +so the C library function passes +.I name +without the preceding slash (i.e., +.IR name+1 ) +to the system call. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH BUGS +Before Linux 2.6.14, +the process umask was not applied to the permissions specified in +.IR mode . +.SH SEE ALSO +.BR mq_close (3), +.BR mq_getattr (3), +.BR mq_notify (3), +.BR mq_receive (3), +.BR mq_send (3), +.BR mq_unlink (3), +.BR mq_overview (7) |