+++ /dev/null
-'\" t
-.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
-.\"
-.\" %%%LICENSE_START(VERBATIM)
-.\" Permission is granted to make and distribute verbatim copies of this
-.\" manual provided the copyright notice and this permission notice are
-.\" preserved on all copies.
-.\"
-.\" Permission is granted to copy and distribute modified versions of this
-.\" manual under the conditions for verbatim copying, provided that the
-.\" entire resulting derived work is distributed under the terms of a
-.\" permission notice identical to this one.
-.\"
-.\" Since the Linux kernel and libraries are constantly changing, this
-.\" manual page may be incorrect or out-of-date. The author(s) assume no
-.\" responsibility for errors or omissions, or for damages resulting from
-.\" the use of the information contained herein. The author(s) may not
-.\" have taken the same level of care in the production of this manual,
-.\" which is licensed free of charge, as they might when working
-.\" professionally.
-.\"
-.\" Formatted or processed versions of this manual, if unaccompanied by
-.\" the source, must acknowledge the copyright and authors of this work.
-.\" %%%LICENSE_END
-.\"
-.TH MQ_NOTIFY 3 2014-04-06 "Linux" "Linux Programmer's Manual"
-.SH NAME
-mq_notify \- register for notification when a message is available
-.SH SYNOPSIS
-.nf
-.B #include <mqueue.h>
-.sp
-.BI "int mq_notify(mqd_t " mqdes ", const struct sigevent *" sevp );
-.fi
-.sp
-Link with \fI\-lrt\fP.
-.SH DESCRIPTION
-.BR mq_notify ()
-allows the calling process to register or unregister for delivery of
-an asynchronous notification when a new message arrives on
-the empty message queue referred to by the descriptor
-.IR mqdes .
-
-The
-.I sevp
-argument is a pointer to a
-.I sigevent
-structure.
-For the definition and general details of this structure, see
-.BR sigevent (7).
-.PP
-If
-.I sevp
-is a non-null pointer, then
-.BR mq_notify ()
-registers the calling process to receive message notification.
-The
-.I sigev_notify
-field of the
-.I sigevent
-structure to which
-.I sevp
-points specifies how notification is to be performed.
-This field has one of the following values:
-.TP
-.B SIGEV_NONE
-A "null" notification: the calling process is registered as the target
-for notification, but when a message arrives, no notification is sent.
-.\" When is SIGEV_NONE useful?
-.TP
-.B SIGEV_SIGNAL
-Notify the process by sending the signal specified in
-.IR sigev_signo .
-See
-.BR sigevent (7)
-for general details.
-The
-.I si_code
-field of the
-.I siginfo_t
-structure will be set to
-.BR SI_MESGQ .
-In addition,
-.\" I don't know of other implementations that set
-.\" si_pid and si_uid -- MTK
-.I si_pid
-will be set to the PID of the process that sent the message, and
-.I si_uid
-will be set to the real user ID of the sending process.
-.TP
-.B SIGEV_THREAD
-Upon message delivery, invoke
-.I sigev_notify_function
-as if it were the start function of a new thread.
-See
-.BR sigevent (7)
-for details.
-.PP
-Only one process can be registered to receive notification
-from a message queue.
-
-If
-.I sevp
-is NULL, and the calling process is currently registered to receive
-notifications for this message queue, then the registration is removed;
-another process can then register to receive a message notification
-for this queue.
-
-Message notification occurs only when a new message arrives and
-the queue was previously empty.
-If the queue was not empty at the time
-.BR mq_notify ()
-was called, then a notification will occur only after
-the queue is emptied and a new message arrives.
-
-If another process or thread is waiting to read a message
-from an empty queue using
-.BR mq_receive (3),
-then any message notification registration is ignored:
-the message is delivered to the process or thread calling
-.BR mq_receive (3),
-and the message notification registration remains in effect.
-
-Notification occurs once: after a notification is delivered,
-the notification registration is removed,
-and another process can register for message notification.
-If the notified process wishes to receive the next notification,
-it can use
-.BR mq_notify ()
-to request a further notification.
-This should be done before emptying all unread messages from the queue.
-(Placing the queue in nonblocking mode is useful for emptying
-the queue of messages without blocking once it is empty.)
-.SH RETURN VALUE
-On success
-.BR mq_notify ()
-returns 0; on error, \-1 is returned, with
-.I errno
-set to indicate the error.
-.SH ERRORS
-.TP
-.B EBADF
-The descriptor specified in
-.I mqdes
-is invalid.
-.TP
-.B EBUSY
-Another process has already registered to receive notification
-for this message queue.
-.TP
-.B EINVAL
-.I sevp\->sigev_notify
-is not one of the permitted values; or
-.I sevp\->sigev_notify
-is
-.B SIGEV_SIGNAL
-and
-.I sevp\->sigev_signo
-is not a valid signal number.
-.TP
-.B ENOMEM
-Insufficient memory.
-.PP
-POSIX.1-2008 says that an implementation
-.I may
-generate an
-.B EINVAL
-.\" Linux does not do this
-error if
-.I sevp
-is NULL, and the caller is not currently registered to receive
-notifications for the queue
-.IR mqdes .
-.SH CONFORMING TO
-POSIX.1-2001.
-.SH EXAMPLE
-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.
-.SS Program source
-.nf
-#include <pthread.h>
-#include <mqueue.h>
-#include <stdio.h>
-#include <stdlib.h>
-#include <unistd.h>
-
-#define handle_error(msg) \\
- do { perror(msg); exit(EXIT_FAILURE); } while (0)
-
-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);
-
- /* Determine max. msg size; allocate buffer to receive msg */
-
- if (mq_getattr(mqdes, &attr) == \-1)
- handle_error("mq_getattr");
- buf = malloc(attr.mq_msgsize);
- if (buf == NULL)
- handle_error("malloc");
-
- nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL);
- if (nr == \-1)
- handle_error("mq_receive");
-
- printf("Read %zd bytes from MQ\\n", nr);
- free(buf);
- exit(EXIT_SUCCESS); /* Terminate the process */
-}
-
-int
-main(int argc, char *argv[])
-{
- mqd_t mqdes;
- struct sigevent sev;
-
- if (argc != 2) {
- fprintf(stderr, "Usage: %s <mq\-name>\\n", argv[0]);
- exit(EXIT_FAILURE);
- }
-
- mqdes = mq_open(argv[1], O_RDONLY);
- if (mqdes == (mqd_t) \-1)
- handle_error("mq_open");
-
- sev.sigev_notify = SIGEV_THREAD;
- sev.sigev_notify_function = tfunc;
- sev.sigev_notify_attributes = NULL;
- sev.sigev_value.sival_ptr = &mqdes; /* Arg. to thread func. */
- if (mq_notify(mqdes, &sev) == \-1)
- handle_error("mq_notify");
-
- pause(); /* Process will be terminated by thread function */
-}
-.fi
-.SH SEE ALSO
-.BR mq_close (3),
-.BR mq_getattr (3),
-.BR mq_open (3),
-.BR mq_receive (3),
-.BR mq_send (3),
-.BR mq_unlink (3),
-.BR mq_overview (7),
-.BR sigevent (7)
-.SH COLOPHON
-This page is part of release 3.79 of the Linux
-.I man-pages
-project.
-A description of the project,
-information about reporting bugs,
-and the latest version of this page,
-can be found at
-\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
