# mq_notify

## 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.
    


## NAME



           mq_notify — notify process that a message is available (**REALTIME**)
    


## SYNOPSIS



           #include <mqueue.h>
    
           int mq_notify(mqd_t _mqdes_ , const struct sigevent *_notification_);
    


## DESCRIPTION



           If the argument _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, _mqdes_.  The notification specified by the _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.
    
           If _notification_ is NULL and the process is currently registered
           for notification by the specified message queue, the existing
           registration shall be removed.
    
           When the notification is sent to the registered process, its
           registration shall be removed. The message queue shall then be
           available for registration.
    
           If a process has registered for notification of message arrival at
           a message queue and some thread is blocked in _mq_receive_() or
           _mq_timedreceive_() waiting to receive a message when a message
           arrives at the queue, the arriving message shall satisfy the
           appropriate _mq_receive_() or _mq_timedreceive_(), respectively. The
           resulting behavior is as if the message queue remains empty, and
           no notification shall be sent.
    


## RETURN VALUE



           Upon successful completion, the _mq_notify_() function shall return
           a value of zero; otherwise, the function shall return a value of
           -1 and set _errno_ to indicate the error.
    


## ERRORS



           The _mq_notify_() function shall fail if:
    
           **EBADF** The _mqdes_ argument is not a valid message queue descriptor.
    
           **EBUSY** A process is already registered for notification by the
                  message queue.
    
           The _mq_notify_() function may fail if:
    
           **EINVAL** The _notification_ argument is NULL and the process is
                  currently not registered.
    
           _The following sections are informative._
    


## 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.
    
               #include <pthread.h>
               #include <mqueue.h>
               #include <assert.h>
               #include <stdio.h>
               #include <stdlib.h>
               #include <unistd.h>
    
               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 maximum msg size; allocate buffer to receive msg */
    
                   if (mq_getattr(mqdes, &attr) == -1) {
                       perror("mq_getattr");
                       exit(EXIT_FAILURE);
                   }
                   buf = malloc(attr.mq_msgsize);
    
                   if (buf == NULL) {
                       perror("malloc");
                       exit(EXIT_FAILURE);
                   }
    
                   nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL);
                   if (nr == -1) {
                       perror("mq_receive");
                       exit(EXIT_FAILURE);
                   }
    
                   printf("Read %ld bytes from message queue\n", (long) nr);
                   free(buf);
                   exit(EXIT_SUCCESS);         /* Terminate the process */
               }
    
               int
               main(int argc, char *argv[])
               {
                   mqd_t mqdes;
                   struct sigevent not;
    
                   assert(argc == 2);
    
                   mqdes = mq_open(argv[1], O_RDONLY);
                   if (mqdes == (mqd_t) -1) {
                       perror("mq_open");
                       exit(EXIT_FAILURE);
                   }
    
                   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, &not) == -1) {
                       perror("mq_notify");
                       exit(EXIT_FAILURE);
                   }
    
                   pause();    /* Process will be terminated by thread function */
               }
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *