syslog -s [-r host] [-l level] message...

     syslog -s [-r host] -k key val [key val] ...

     syslog [-w] [-F format] expression

     syslog -p expression

     syslog -c process [filter]

DESCRIPTION

     syslog is a command-line utility for a variety of tasks relating to the
     Apple System Log facility.  It provides mechanisms for sending and view-
     ing log messages, pruning the contents of the system's log message data
     store, and for controlling the flow of log messages from client pro-
     cesses.

     When invoked with the -help option, syslog prints a usage message.

   SENDING MESSAGES
     The -s option is used send log messages to the syslogd(8) log message
     daemon, either locally or to a remote server if the -r host option in
     used.

     There are two main forms of the command.  If the -k option is used, then
     it must be followed by a list of keys and values.  A structured message
     will be sent to the server with the keys and values given as arguments.
     If a key or a value has embedded white space, it must be enclosed in
     quotes.

     If the -k option is not specified, then the rest of the command line is
     treated as the message text.  The text may be preceded by -l level to set
     the log level (priority) of the message.  Levels may be an integer value
     corresponding the the log levels specified in syslog(3) or asl(3), or
     they may be a string.  String values are case insensitive, and should be
     one of:

     Emergency     (level 0)
     Alert         (level 1)
     Critical      (level 2)
     Error         (level 3)
     Warning       (level 4)
     Notice        (level 5)
     Info          (level 6)
     Debug         (level 7)

     The string ``Panic'' is an alias for ``Emergency''.  syslog only requires
     one or two leading characters for a level specification.  A single char-
     acter suffices in most cases.  Use ``P'' or ``Em'' for Panic / Emergency,
     and ``Er'' or ``X'' for Error).

     Another module saves messages in a data store, which may be searched
     using the syslog command.

     If invoked with no arguments, syslog simply prints all of the messages
     saved in the data store.  If the -w option is used, syslog waits for new
     messages to be added to the data store.  Messages already in the store
     are ignored.  This usage is similar to watching a log file using, e.g.

           tail -f /var/log/system.log

     Messages are printed in a format similar to that used in the system.log
     file, except that the message priority level is printed between angle-
     brackets.

     The -u option forces all time stamps to be printed using UTC.  This over-
     rides printing of time stamps using the local time zone.

     The output format may by changed by specifying the -F format option.  The
     value of format may be one of the following:

     bsd   Format used by the syslogd daemon for system log files, e.g.
           /var/log/system.log.

     std   Standard (default) format.  Similar to ``bsd'', but includes the
           message priority level.

     raw   Prints the complete message structure.  Each key/value pair is
           enclosed in square brackets.  Embedded closing brackets and white
           space are escaped.  Time stamps are printed using UTC rather than
           being converted to the local time zone.

     The value of the format argument may also be a custom print format
     string.  A custom format should in most cases be enclosed in single
     quotes to prevent the shell from substituting special characters and
     breaking at white space.

     Custom format strings may include variables of the form ``$Name'' (or
     ``$(Name)'' if the variable is not delimited by whitespace) which will be
     expanded to the associated with the named key.  For example, the command:

           syslog -F '$Time $Host $(Sender)[$(PID)]: $Message'

     produces output similar to the ``bsd'' format.

     If no further command line options are specified, syslog displays all
     messages, either all those saved in the data store, or all new messages
     if -w is used.  However, an expression may be specified using the -k and
     -o options.

   EXPRESSIONS
     Expressions specify matching criteria.  They may be used when reading
     messages to filter for messages of interest.  Expressions are also

     eq   equal
     ne   not equal
     gt   greater than
     ge   greater than or equal to
     lt   less than
     le   less than or equal to

     Additionally, the operator may be preceded by one or more of the follow-
     ing modifiers:

     C    case-fold
     R    regular expression (see regex(3))
     S    substring
     A    prefix
     Z    suffix
     N    numeric comparison

     An simple expression matches a message if all of the key-value operations
     match.  Logically, the result is an AND of all of key-value operations.
     The -o option separates simple expressions and provides an OR operation.
     If two or more simple expressions are given, separated by -o options,
     then a match occurs is a message matches any of the simple expressions.
     For example, to find all messages which have either a ``Sender'' value of
     ``portmap'' or that have a numeric priority level of 4 or less:

           syslog -k Sender portmap -o -k Level Nle 4

     A special convention exists for matching time stamps.  An unsigned inte-
     ger value is regarded as the given number of seconds since 0 hours, 0
     minutes, 0 seconds, January 1, 1970, Coordinated Universal Time.  An neg-
     ative integer value is regarded as the given number of seconds before the
     current time.  For example, to find all messages of priority level 3
     (error) or less which were logged in the last 30 seconds:

           syslog -k Level Nle 3 -k Time ge -30

     a relative time value may be optionally followed by one of the characters
     ``s'', ``m'', ``h'', ``d'', or ``w'' to specify seconds, minutes, hours,
     days, or weeks respectively.  Upper case may be used equivalently.  A
     week is taken to be 7 complete days (i.e. 604800 seconds).

   PRUNING
     The Apple System Log facility saves received messages, subject to filter-
     ing criteria described in the FILTERING CONTROLS section below.  Pruning
     is required to prevent unlimited growth of the data store.

     The syslogd daemon itself will prune the data store shortly after it
     starts up.  See the syslogd(8) manual for more details on startup prun-
     ing.  During extended operation of syslogd, pruning is accomplished by
     using the -p option of syslog.  The -p option must be followed by an
     expression (see above).  The contents of the data store are filtered
     spending time sending messages that are in most cases unnecessary.

     The -c option may be used to control filtering.  In addition to the
     internal filter value that processes may set as described above, the sys-
     tem maintains a global ``master'' filter.  This filter is normally
     ``off'', meaning that it has no effect.  If a value is set for the master
     filter, it overrides the local filter for all processes.  Root user
     access is required to set the master filter value.

     The current setting of the master filter mask may be inspected using:

           syslog -c 0

     The value of the master filter mask my be set by providing a second argu-
     ment following -c 0.  The value may a set of characters from the set
     ``pacewnid''.  These correspond to the priority levels Emergency (Panic),
     Alert, Critical, Error, Warning, Notice, Info, and Debug.  The character
     ``x'' may be used for Error, as it is used for sending messages.  The
     master filter may be unset with:

           syslog -c 0 off

     Since it is common to use the filter as a ``cutoff'' mechanism, for exam-
     ple to cut off messages with Debug and Info priority, a single character
     from the list above may be specified, preceded by a minus sign.  In this
     case, syslog uses a filter mask starting at level 0 (Emergency) ``up to''
     the given level.  For example, to set the master filter level to cause
     all processes to log messages from Emergency up to Debug:

           syslog -c 0 -d

     While the master filter level may be set to control the messages produced
     by all processes, another filter mask may be specified for an individual
     process.  If a per-process filter mask is set, it overrides both the
     local filter mask and the master filter mask.  The current setting for a
     per-process filter mask may be inspected using -c process, where process
     is either a PID or the name of a process.  If a name is used, it must
     uniquely identify a process.  To set a per-process filter mask, an second
     argument may be supplied following -c process as described above for the
     master filter mask.  Root access is required to set the per-process fil-
     ter mask for system (UID 0) processes.

     The filtering described above takes place in the client library to deter-
     mine which messages are sent to the syslogd daemon.  The daemon also con-
     tains a filter which determines which messages are saved in the data
     store.  Note that this additionally determines which messages are seen
     when reading messages using the syslog utility.

     The default data store filter mask saves messages with priority levels
     from Emergency to Notice (level 0 to 5).  The level may be inspected
     using:

Mac OS X                       October 18, 2004                       Mac OS X