1.\" Copyright (c) 2006-2011 Apple Inc. All rights reserved. 2.\" 3.\" @APPLE_LICENSE_HEADER_START@ 4.\" 5.\" This file contains Original Code and/or Modifications of Original Code 6.\" as defined in and that are subject to the Apple Public Source License 7.\" Version 2.0 (the 'License'). You may not use this file except in 8.\" compliance with the License. Please obtain a copy of the License at 9.\" http://www.opensource.apple.com/apsl/ and read it before using this 10.\" file. 11.\" 12.\" The Original Code and all software distributed under the License are 13.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 14.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 15.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 16.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 17.\" Please see the License for the specific language governing rights and 18.\" limitations under the License. 19.\" 20.\" @APPLE_LICENSE_HEADER_END@ 21.\" 22.\" 23.Dd November 4, 2011 24.Dt notifyutil 1 25.Os "Mac OS X" 26.Sh NAME 27.Nm notifyutil 28.Nd notification command line utility 29.Sh SYNOPSIS 30.Nm 31.Op Fl q 32.Op Fl v 33.Op Fl z Ar msec 34.Op Fl M 35.Op Fl R 36.Op command Li ... 37.Pp 38.Sh DESCRIPTION 39.Nm 40is a command-line utility for interacting with the 41.Xr notify 3 42notification system and the 43.Xr notifyd 8 44server. 45It may be used to post notifications, detect and report notifications, 46and to examine and set the state values associated with notification keys. 47.Pp 48If 49.Nm 50is used to monitor one or more notification keys, 51it prints the notification key when the corresponding notification is received. 52The 53.Fl v 54(verbose) 55and 56.Fl q 57(quiet) flags, if specified, modify the output behavior. 58.Pp 59The 60.Fl v 61flag causes 62.Nm 63to print a time stamp, the notification key, the current state value for that key, 64and the type of the notification (port, file, etc). 65The 66.Fl q 67flag supresses any output except for state values fetched following a 68.Fl g 69command. 70.Pp 71Commands listed in the table below are processed in left to right order from the command line. 72.Pp 73.Bl -tag -width "-signal [#]" -compact -offset indent 74.It Fl p Ar key 75Post a notification for 76.Ar key . 77.It Fl w Ar key 78Register for 79.Ar key 80and wait forever for notifications. 81.It Fl Ar # Ar key 82Register for 83.Ar key 84and wait for 85.Ar # 86(an integer) notifications. 87.It "" 88.Li E.g. 89.Fl 1 Ar key 90waits for a single notification. 91.It Fl g Ar key 92Get state value for 93.Ar key . 94.It Fl s Ar key Ar val 95Set state value for 96.Ar key . 97.It Fl port 98Use mach port notifications for subsequent 99.Fl w 100or 101.Fl Ar # 102registrations. 103.It "" 104This is the default registration type. 105.It Fl file 106Use file descriptor notifications for subsequent registrations. 107.It Fl check 108Use shared memory notifications for subsequent registrations. 109.It Fl signal Op Ar # 110Use signal notifications for subsequent registrations. 111.It "" 112Signal 1 (HUP) is the default, but an alternate signal may be specified. 113.It Fl dispatch 114Use dispatch for subsequent registrations. 115.El 116.Pp 117When invoked with any combination of 118.Fl w 119and 120.Fl Ar # 121actions, 122.Nm 123registers for notification for the specified key(s). 124If any key is given with a 125.Fl w 126action, 127.Nm 128runs until interrupted with Control-C. 129If all registrations are invoked with 130.Fl Ar # , 131the program continues to run until the corresponding number of notifications for each key have been received. 132.Pp 133By default, 134.Nm 135uses mach port registration (using 136.Fn notify_register_mach_port ) 137for keys given with a 138.Fl w 139or 140.Fl Ar # 141flag. 142The 143.Fl file 144command causes 145.Nm 146to use 147.Fn notify_register_file_descriptor 148for any subsequent 149.Fl w 150or 151.Fl Ar # 152registrations. 153Similarly, 154.Fl check 155causes 156.Nm 157to use 158.Fn notify_register_check 159for subsequent registrations, 160.Fl signal 161switches to 162.Fn notify_register_signal , 163and 164.Fl dispatch 165causes it to use 166.Fn notify_register_dispatch 167for subsequent registrations. 168.Pp 169If any registrations are made following the use of the 170.Fl check 171command, 172.Nm 173will start a timer and check for shared memory notifications every 100 milliseconds. 174An alternate timer value may be set following the 175.Fl z 176flag. 177.Pp 178The 179.Fl M 180flag causes 181.Nm 182to use multiplex all notifications over a single mach connection with 183.Nm notifyd . 184Notifications (except shared memory notifications) 185are received and redistributed by a dispatch handler. 186.Pp 187The 188.Fl R 189flag causes 190.Nm notifyutil 191to regenerate all its registrations in the unlikely event that 192.Nm notifyd 193restarts. 194.Pp 195Note that a notification key and its associated state variable only exist 196when there are one or more current registrations for that key. 197Setting the state for a key that has no registrations has no effect. 198Thus the command 199.Pp 200.Dl notifyutil -s foo.bar 123 -g foo.bar 201.Pp 202will print 203.Pp 204.Dl foo.bar 0 205.Pp 206unless foo.bar is registered by some other process. 207However, the command 208.Pp 209.Dl notifyutil -w foo.bar -s foo.bar 123 -g foo.bar 210.Pp 211prints 212.Pp 213.Dl foo.bar 123 214.Pp 215since the 216.Dq -w foo.bar 217registration ensures the key and its state variable exist before the value is set, 218and continue to exist when the value is fetched. 219.Sh SEE ALSO 220notify(3), notifyd(8) 221