mq_notify.3p (5641B)
- '\" et
- .TH MQ_NOTIFY "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_notify
- \(em notify process that a message is available
- (\fBREALTIME\fP)
- .SH SYNOPSIS
- .LP
- .nf
- #include <mqueue.h>
- .P
- int mq_notify(mqd_t \fImqdes\fP, const struct sigevent *\fInotification\fP);
- .fi
- .SH DESCRIPTION
- If the argument
- .IR notification
- is not NULL, this function shall register the calling process to be
- notified of message arrival at an empty message queue associated with
- the specified message queue descriptor,
- .IR mqdes .
- The notification specified by the
- .IR notification
- argument shall be sent to the process when the message queue transitions
- from empty to non-empty. At any time, only one process may be
- registered for notification by a message queue. If the calling process
- or any other process has already registered for notification of message
- arrival at the specified message queue, subsequent attempts to register
- for that message queue shall fail.
- .P
- If
- .IR notification
- is NULL and the process is currently registered for notification by the
- specified message queue, the existing registration shall be removed.
- .P
- When the notification is sent to the registered process, its
- registration shall be removed. The message queue shall then be available
- for registration.
- .P
- If a process has registered for notification of message arrival at a
- message queue and some thread is blocked in
- \fImq_receive\fR()
- or
- \fImq_timedreceive\fR()
- waiting to receive a message when a message arrives at the queue, the
- arriving message shall satisfy the appropriate
- \fImq_receive\fR()
- or
- \fImq_timedreceive\fR(),
- respectively. The resulting behavior is as if the message queue remains
- empty, and no notification shall be sent.
- .SH "RETURN VALUE"
- Upon successful completion, the
- \fImq_notify\fR()
- function shall return a value of zero; otherwise, the function shall
- return a value of \-1 and set
- .IR errno
- to indicate the error.
- .SH ERRORS
- The
- \fImq_notify\fR()
- function shall fail if:
- .TP
- .BR EBADF
- The
- .IR mqdes
- argument is not a valid message queue descriptor.
- .TP
- .BR EBUSY
- A process is already registered for notification by the message queue.
- .P
- The
- \fImq_notify\fR()
- function may fail if:
- .TP
- .BR EINVAL
- The
- .IR notification
- argument is NULL and the process is currently not registered.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- The following program registers a notification request for the message
- queue named in its command-line argument. Notification is performed
- by creating a thread. The thread executes a function which reads one
- message from the queue and then terminates the process.
- .sp
- .RS 4
- .nf
- #include <pthread.h>
- #include <mqueue.h>
- #include <assert.h>
- #include <stdio.h>
- #include <stdlib.h>
- #include <unistd.h>
- .P
- static void /* Thread start function */
- tfunc(union sigval sv)
- {
- struct mq_attr attr;
- ssize_t nr;
- void *buf;
- mqd_t mqdes = *((mqd_t *) sv.sival_ptr);
- .P
- /* Determine maximum msg size; allocate buffer to receive msg */
- .P
- if (mq_getattr(mqdes, &attr) == -1) {
- perror("mq_getattr");
- exit(EXIT_FAILURE);
- }
- buf = malloc(attr.mq_msgsize);
- .P
- if (buf == NULL) {
- perror("malloc");
- exit(EXIT_FAILURE);
- }
- .P
- nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL);
- if (nr == -1) {
- perror("mq_receive");
- exit(EXIT_FAILURE);
- }
- .P
- printf("Read %ld bytes from message queue\en", (long) nr);
- free(buf);
- exit(EXIT_SUCCESS); /* Terminate the process */
- }
- .P
- int
- main(int argc, char *argv[])
- {
- mqd_t mqdes;
- struct sigevent not;
- .P
- assert(argc == 2);
- .P
- mqdes = mq_open(argv[1], O_RDONLY);
- if (mqdes == (mqd_t) -1) {
- perror("mq_open");
- exit(EXIT_FAILURE);
- }
- .P
- not.sigev_notify = SIGEV_THREAD;
- not.sigev_notify_function = tfunc;
- not.sigev_notify_attributes = NULL;
- not.sigev_value.sival_ptr = &mqdes; /* Arg. to thread func. */
- if (mq_notify(mqdes, ¬) == -1) {
- perror("mq_notify");
- exit(EXIT_FAILURE);
- }
- .P
- pause(); /* Process will be terminated by thread function */
- }
- .fi
- .P
- .RE
- .SH "APPLICATION USAGE"
- None.
- .SH RATIONALE
- None.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fImq_open\fR\^(\|)",
- .IR "\fImq_send\fR\^(\|)",
- .IR "\fImq_receive\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 .