summaryrefslogtreecommitdiffstats
path: root/man3/mq_getattr.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/mq_getattr.3')
-rw-r--r--man3/mq_getattr.3230
1 files changed, 230 insertions, 0 deletions
diff --git a/man3/mq_getattr.3 b/man3/mq_getattr.3
new file mode 100644
index 0000000..7c183e7
--- /dev/null
+++ b/man3/mq_getattr.3
@@ -0,0 +1,230 @@
+'\" t
+.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH mq_getattr 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+mq_getattr, mq_setattr \- get/set message queue attributes
+.SH LIBRARY
+Real-time library
+.RI ( librt ", " \-lrt )
+.SH SYNOPSIS
+.nf
+.B #include <mqueue.h>
+.PP
+.BI "int mq_getattr(mqd_t " mqdes ", struct mq_attr *" attr );
+.BI "int mq_setattr(mqd_t " mqdes ", const struct mq_attr *restrict " newattr ,
+.BI " struct mq_attr *restrict " oldattr );
+.fi
+.SH DESCRIPTION
+.BR mq_getattr ()
+and
+.BR mq_setattr ()
+respectively retrieve and modify attributes of the message queue
+referred to by the message queue descriptor
+.IR mqdes .
+.PP
+.BR mq_getattr ()
+returns an
+.I mq_attr
+structure in the buffer pointed by
+.IR attr .
+This structure is defined as:
+.PP
+.in +4n
+.EX
+struct mq_attr {
+ long mq_flags; /* Flags: 0 or O_NONBLOCK */
+ long mq_maxmsg; /* Max. # of messages on queue */
+ long mq_msgsize; /* Max. message size (bytes) */
+ long mq_curmsgs; /* # of messages currently in queue */
+};
+.EE
+.in
+.PP
+The
+.I mq_flags
+field contains flags associated with the open message queue description.
+This field is initialized when the queue is created by
+.BR mq_open (3).
+The only flag that can appear in this field is
+.BR O_NONBLOCK .
+.PP
+The
+.I mq_maxmsg
+and
+.I mq_msgsize
+fields are set when the message queue is created by
+.BR mq_open (3).
+The
+.I mq_maxmsg
+field is an upper limit on the number of messages
+that may be placed on the queue using
+.BR mq_send (3).
+The
+.I mq_msgsize
+field is an upper limit on the size of messages
+that may be placed on the queue.
+Both of these fields must have a value greater than zero.
+Two
+.I /proc
+files that place ceilings on the values for these fields are described in
+.BR mq_overview (7).
+.PP
+The
+.I mq_curmsgs
+field returns the number of messages currently held in the queue.
+.PP
+.BR mq_setattr ()
+sets message queue attributes using information supplied in the
+.I mq_attr
+structure pointed to by
+.IR newattr .
+The only attribute that can be modified is the setting of the
+.B O_NONBLOCK
+flag in
+.IR mq_flags .
+The other fields in
+.I newattr
+are ignored.
+If the
+.I oldattr
+field is not NULL,
+then the buffer that it points to is used to return an
+.I mq_attr
+structure that contains the same information that is returned by
+.BR mq_getattr ().
+.SH RETURN VALUE
+On success
+.BR mq_getattr ()
+and
+.BR mq_setattr ()
+return 0; on error, \-1 is returned, with
+.I errno
+set to indicate the error.
+.SH ERRORS
+.TP
+.B EBADF
+The message queue descriptor specified in
+.I mqdes
+is invalid.
+.TP
+.B EINVAL
+.I newattr\->mq_flags
+contained set bits other than
+.BR O_NONBLOCK .
+.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_getattr (),
+.BR mq_setattr ()
+T} Thread safety MT-Safe
+.TE
+.sp 1
+.SH VERSIONS
+On Linux,
+.BR mq_getattr ()
+and
+.BR mq_setattr ()
+are library functions layered on top of the
+.BR mq_getsetattr (2)
+system call.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.SH EXAMPLES
+The program below can be used to show the default
+.I mq_maxmsg
+and
+.I mq_msgsize
+values that are assigned to a message queue that is created with a call to
+.BR mq_open (3)
+in which the
+.I attr
+argument is NULL.
+Here is an example run of the program:
+.PP
+.in +4n
+.EX
+$ \fB./a.out /testq\fP
+Maximum # of messages on queue: 10
+Maximum message size: 8192
+.EE
+.in
+.PP
+Since Linux 3.5, the following
+.I /proc
+files (described in
+.BR mq_overview (7))
+can be used to control the defaults:
+.PP
+.in +4n
+.EX
+$ \fBuname \-sr\fP
+Linux 3.8.0
+$ \fBcat /proc/sys/fs/mqueue/msg_default\fP
+10
+$ \fBcat /proc/sys/fs/mqueue/msgsize_default\fP
+8192
+.EE
+.in
+.SS Program source
+\&
+.\" SRC BEGIN (mq_getattr.c)
+.EX
+#include <fcntl.h>
+#include <mqueue.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/stat.h>
+#include <unistd.h>
+\&
+#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e
+ } while (0)
+\&
+int
+main(int argc, char *argv[])
+{
+ mqd_t mqd;
+ struct mq_attr attr;
+\&
+ if (argc != 2) {
+ fprintf(stderr, "Usage: %s mq\-name\en", argv[0]);
+ exit(EXIT_FAILURE);
+ }
+\&
+ mqd = mq_open(argv[1], O_CREAT | O_EXCL, 0600, NULL);
+ if (mqd == (mqd_t) \-1)
+ errExit("mq_open");
+\&
+ if (mq_getattr(mqd, &attr) == \-1)
+ errExit("mq_getattr");
+\&
+ printf("Maximum # of messages on queue: %ld\en", attr.mq_maxmsg);
+ printf("Maximum message size: %ld\en", attr.mq_msgsize);
+\&
+ if (mq_unlink(argv[1]) == \-1)
+ errExit("mq_unlink");
+\&
+ exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR mq_close (3),
+.BR mq_notify (3),
+.BR mq_open (3),
+.BR mq_receive (3),
+.BR mq_send (3),
+.BR mq_unlink (3),
+.BR mq_overview (7)