diff options
Diffstat (limited to '')
| -rw-r--r-- | man3/mq_getattr.3 | 230 |
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) |