notifyutil.1   [plain text]


.\" Copyright (c) 2006-2010 Apple Inc. All rights reserved.
.\"
.\" @APPLE_LICENSE_HEADER_START@
.\"
.\" This file contains Original Code and/or Modifications of Original Code
.\" as defined in and that are subject to the Apple Public Source License
.\" Version 2.0 (the 'License'). You may not use this file except in
.\" compliance with the License. Please obtain a copy of the License at
.\" http://www.opensource.apple.com/apsl/ and read it before using this
.\" file.
.\"
.\" The Original Code and all software distributed under the License are
.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
.\" Please see the License for the specific language governing rights and
.\" limitations under the License.
.\"
.\" @APPLE_LICENSE_HEADER_END@
.\"
.\"
.Dd January 20, 2010
.Dt notifyutil 1
.Os "Mac OS X"
.Sh NAME
.Nm notifyutil
.Nd notification command line utility
.Sh SYNOPSIS
.Nm
.Op Fl q
.Op Fl v
.Op Fl t
.Op Fl T
.Op Fl f
.Op Fl p Ar key
.Op Fl w Ar key
.Op Fl Ar # Ar key
.Op Fl g Ar key
.Op Fl s Ar key Ar val
.Li ...
.Pp
.Sh DESCRIPTION
.Nm
is a command-line utility for interacting with the
.Xr notifyd 8
notification server.
It may be used to post notifications, detect and report notifications,
and to examine and set the state value associated with a notification key.
.Pp
The following table summarizes the actions that may be performed.
.Pp
.Bl -tag -width "-s key val" -compact -offset indent
.It Fl p Ar key
Post a notification for
.Ar key .
.It Fl w Ar key
Register for
.Ar key
and wait for notifications.
.It Fl Ar # Ar key
Register for
.Ar key
and wait for
.Ar #
(an integer) notifications.
.Li E.g.
.Fl 1 Ar key
waits for a single notification.
.It Fl g Ar key
Get state value for
.Ar key .
.It Fl s Ar key Ar val
Set state value for
.Ar key .
.El
.Pp
When invoked with any combination of
.Fl w
and
.Fl Ar #
actions,
.Nm
registers for notification for the specified key(s).
If any key is given with a
.Fl w
action,
.Nm
runs until interrupted with Control-C.
If all registrations are invoked with
.Fl Ar # ,
the program continues to run until the corresponding number of notifications for each key have been received.
.Pp
By default,
.Nm
uses mach port registration for keys given with a
.Fl w
or
.Fl Ar #
option.
The
.Fl f
option causes
.Nm 
to use file descriptor registrations for all keys.
.Pp
When a notification for any key that is being monitored is received,
.Nm
prints the key on a single line on its standard output.
The
.Fl v
(verbose),
.Fl t
(time stamp), 
.Fl T
(microsecond timer)
and
.Fl q
(quiet) flags, if specified, modify the output behavior.
.Pp
The 
.Fl v
flag causes
.Nm
to print both the key and the current state value for that key.
.Pp
The
.Fl t
flag causes
.Nm
to print a time stamp preceding the notification key.
.Pp
The
.Fl T
option prints microsecond timing information as raw seconds with 6 decimal digits.
Microsecond times are printed when a notification is received, and when a notification is posted.
When posting,
.Nm 
collects the time before and after calling
.Fn notify_post .
Note that
.Fl T
overrides
.Fl t .
.Pp
The
.Fl q
flag causes
.Nm
to operate silently.
.Pp
.Nm
processes 
.Fl w ,
.Fl Ar # ,
.Fl p ,
.Fl g ,
and
.Fl s
arguments from left to right.
For example, the following will register for a single notification for the key 
.Dq test.abc
and then post a notification for that key.
.Pp
.Dl notifyutil -1 test.abc -p test.abc
.Sh SEE ALSO
notify(3), notifyd(8)