notify(3) BSD Library Functions Manual notify(3)

NAME
     nnoottiiffyyppoosstt, nnoottiiffyyrreeggiisstteerrcchheecckk, nnoottiiffyyrreeggiisstteerrssiiggnnaall,
     nnoottiiffyyrreeggiisstteerrmmaacchhppoorrtt, nnoottiiffyyrreeggiisstteerrffiilleeddeessccrriippttoorr, nnoottiiffyycchheecckk,
     nnoottiiffyyccaanncceell - event distribution functions

SYNOPSIS
     ##iinncclluuddee <>

     uint32t
     nnoottiiffyyppoosstt(const char *name);

     uint32t
     nnoottiiffyyrreeggiisstteerrcchheecckk(const char *name, int *outtoken);

     uint32t
     nnoottiiffyyrreeggiisstteerrssiiggnnaall(const char *name, int sig, int *outtoken);

     uint32t
     nnoottiiffyyrreeggiisstteerrmmaacchhppoorrtt(const char *name, machportt *notifyport, int flags, int *outtoken);

     uint32t
     nnoottiiffyyrreeggiisstteerrffiilleeddeessccrriippttoorr(const char *name, int *notifyfd, int flags, int *outtoken);

     uint32t
     nnoottiiffyycchheecckk(int token, int *check);

     uint32t
     nnoottiiffyyccaanncceell(int token);

DESCRIPTION
     These routines allow processes to exchange stateless notification events.

     Notifications are associated with names in a namespace shared by all
     clients of the system.  Clients may post notifications for names, and may
     monitor names for posted notifications.  Clients may request notification
     delivery by a number of different methods.

     Clients desiring to monitor names in the notification system must regis-
     ter with the system, providing a name and other information required for
     the desired notification delivery method.  Clients are given an integer
     token representing the registration.

     Notifications may be coalesced in some cases.  Multiple events posted for
     a name in rapid succession may result in a single notification sent to
     clients registered for notification for that name.  Clients checking for
     changes using the notifycheck() routine cannot determine if more than
     one event pas been posted since a previous call to notifycheck() for
     that name.

     "False positives" may occur in notifycheck() when used with a token gen-
     erated by notifyregistercheck() due to implementation constraints.
     This behavior may vary in future releases.

   nnoottiiffyyppoosstt
     This routine causes the system to send a notification for the given name
     to all clients that have registered for notifications of this name.  This
     is the only API required for an appication that only produces notifica-
     tions.

   nnoottiiffyyrreeggiisstteerrcchheecckk
     Registers for passive notification for the given name.  The routine gen-
     erates a token that may be used with the nnoottiiffyycchheecckk() routine to check
     if any notifications have been posted for the name.  The check is imple-
     mented using a shared memory scheme, making the check very fast and effi-
     cient.  The implementation has a limited amount of shared memory, so
     developers are encouraged to use this mechanism sparingly.  It is also
     important to release the resources consumed by a registration with
     nnoottiiffyyccaanncceell() when they are no longer required by the application.

   nnoottiiffyyrreeggiisstteerrssiiggnnaall
     registers a client for notification delivery via a signal.  This fits
     well with the design of many UNIX daemons that use a signal such as
     SIGHUP to reinitialize of reset internal state information.  Clients may
     use the registration token generated by this routine to check for notifi-
     cations using nnoottiiffyycchheecckk().  This allows the application to determine
     if a signal was received as the result of a notification, or is the sig-
     nal was generated by some other source.  It also permits the application
     that registers for signal notification for multiple names to determine
     which name was associated with the notification.

   nnoottiiffyyrreeggiisstteerrmmaacchhppoorrtt
     registers a client for notification delivery via mach messaging.  Notifi-
     cations are delivered by an empty message sent to a mach port.  By
     default, a new port is created by a call to this routine.  A mach port
     previously created by a call to this routine may be used for notifica-
     tions if a pointer to that port is passed in to the routine and
     NOTIFYREUSE is set in the flags parameter.  The notification service
     must be able to extract send rights to the port.

     Note that the kernel limits the size of the message queue for any port.
     If it is important that notifications should not be lost due to queue
     overflow, clients should service messages quickly, and be cautious in
     using the same port for notifications for more than one name.

     A notification message has an empty message body.  The msghid field in
     the mach message header will have the value of the notification token.
     If a port is reused for multiple notification registrations, the msghid
     value may be used to determine which name generated the notification.

   nnoottiiffyyrreeggiisstteerrffiilleeddeessccrriippttoorr
     Register for notification by a write to a file descriptor.

     By default, a new file descriptor is created and a pointer to it is
     returned as the value of the "notifyfd" parameter.  A file descriptor
     created by a previous call to this routine may be used for notifications
     if a pointer to that file descriptor is passed in to the routine and
     NOTIFYREUSE is set in the flags parameter.

     Note that the kernel limits the buffer space for queued writes on a file
     descriptor.  If it is important that notifications should not be lost due
     to queue overflow, clients should service messages quickly, and be cau-
     tious in using the same file descriptor for notifications for more than
     one name.

     Notifications are delivered by an integer value written to the file
     descriptor.  The value will match the notification token for which the
     notification was generated.

   nnoottiiffyycchheecckk
     Checks if any notifications have been posted for a name.  The output
     parameter "check" is set to 0 for false, 1 for true.  A true indication
     is returned the first time notifycheck is called for a token.  Subse-
     quent calls give a true indication when notifications have been posted
     for the name associated with the notification token.

     nnoottiiffyycchheecckk() may be used with any notification token produced by any of
     the notification registration routines.  A fast check based on a shared
     memory implementation is used when the token was generated by
     nnoottiiffyyrreeggiisstteerrcchheecckk().  Other tokens are checked by a call to the noti-
     fication server.

   nnoottiiffyyccaanncceell
     Cancel notification and free resources associated with a notification
     token.  Mach ports and file descriptor associated with a token are
     released (deallocated or closed) when all registration tokens associated
     with the port or file descriptor have been cancelled.

NAMESPACE CONVENTIONS
     Names in the namespace must be NULL-terminated.  Names should be encoded
     as UTF-8 strings.

     The namespace supported by the system is unstructured, but users of this
     API are highly encouraged to follow the reverse-ICANN domain name conven-
     tion used for Java package names and for System Preferences on Mac OS X.
     For example, "com.mydomain.example.event".

     Apple Computer reserves the portion of the namespace prefixed by
     "com.apple.".  This policy is not enforced in the current implementation,
     but may be in the future.

     Third party developers are encouraged to choose a prefix for names that
     will avoid conflicts in the shared namespace.

     The portion of the namespece prefixed by the string "self." is set aside
     for private use by applications.  That is, each client may use that part
     of the namespace for intra-process notifications.  These notifications
     are private to each individual process and are not propagated between
     processes.

UUSSAAGGEE EEXXAAMMPPLLEESS
     A notification producer.

         #include 
         ...

         notifypost("com.eg.random.event");

     A client using notifycheck() to determine when to invalidate a cache.

         #include 
         #include 
         #include 

         int
         main(int argc, char *argv[])
         {
             int status, token, check;

             status = notifyregistercheck("com.eg.update", &token);
             if (status != NOTIFYSTATUSOK)
             {
                fprintf(stderr, "registration failed (%u)\n", status);
                exit(status);
             }

             buildmycache();

             ...

             status = notifycheck(token, &check);
             if ((status == NOTIFYSTATUSOK) && (check != 0))
             {
                /* An update has occurred - invalidate the cache */
                resetmycache();
             }

             ...

     A client using file descriptor notifications.

         #include 
         #include 
         #include 
         #include 
         #include 
         #include 
         #include 
         #include 

         int
         main(int argc, char *argv[])
         {
             int nf, status, rtoken, qtoken, t;
             fdset readfds;

             status = notifyregisterfiledescriptor("com.eg.random.event",
                &nf, 0, &rtoken);
             if (status != NOTIFYSTATUSOK)
             {
                fprintf(stderr, "registration failed (%u)\n", status);
                exit(status);
             }

             status = notifyregisterfiledescriptor("com.eg.random.quit",
                 &nf, NOTIFYREUSE, &qtoken);
             if (status != NOTIFYSTATUSOK)
             {
                fprintf(stderr, "registration failed (%u)\n", status);
                exit(status);
             }

             FDZERO(&readfds);
             FDSET(nf, &readfds);

             for (;;)
             {
                status = select(nf+1, &readfds, NULL, NULL, NULL);
                if (status <= 0) continue;
                if (!FDISSET(nf, &readfds)) continue;

                status = read(nf, &t, sizeof(int));
                if (status < 0)
                {
                    perror("read");
                    break;
                }

                if (t == rtoken) printf("random event\n");
                else if (t == qtoken) break;
             }

             printf("shutting down0);
             notifycancel(rtoken);
             notifycancel(qtoken);
             exit(0);
         }

HISTORY     These functions first appeared in Mac OS X 10.3.

SEE ALSO
     read(2), select(2), signal(3)

Mac OS X                        March 19, 2003                        Mac OS X