-.\"Copyright (c) 2004-2011 Apple Inc. All rights reserved.
+.\"Copyright (c) 2004-2012 Apple Inc. All rights reserved.
.\"
.\"@APPLE_LICENSE_HEADER_START@
.\"
.Fl x Ar file Ar expression
.D1 ""
.Nm
-.Fl c Ar process Op filter
+.Fl c Ar process Op mask
.D1 ""
.Nm
.Fl config Op options
+.D1 ""
+.Nm
+.Fl module
+.Op name Op action
.Sh DESCRIPTION
.Nm
is a command-line utility for a variety of tasks relating to the Apple System Log (ASL) facility.
Dictionary values are strings.
.El
.Pp
+Each of the format styles above may optionally be followed by a dot character and an integer value, for example:
+.Pp
+.Dl syslog -F std.4
+.Pp
+This causes sub-second time values to be printed.
+In the example above, 4 decimal digits would be printed.
+The sub-second time values come from the value of the TimeNanoSec key in the ASL message.
+If the TimeNanoSec key is missing, a value of zero is used.
+.Pp
The value of the
.Ar format
argument may also be a custom print format string.
When printing using $((Time)(J)), the output format is
.Dq "yyyy-mm-dd hh:mm:ss" ,
without a trailing timezone letter.
+.It $((Time)(JZ))
+Specifies the local timezone.
+The timezone offset from UTC follows the date and time.
+The time is formatted as
+.Dq "yyyy-mm-dd hh:mm:ss[+|-]HH[:MM]" .
+Minutes in the timezone offset are only printed if they are non-zero.
+.It $((Time)(ISO8601))
+Specifies the local timezone and ISO 8601 extended format.
+The timezone offset from UTC follows the date and time.
+The time is formatted as
+.Dq "yyyy-mm-ddThh:mm:ss[+|-]HH[:MM]" .
+Minutes in the timezone offset are only printed if they are non-zero.
+Note that this differs from
+.Dq JZ
+format only in that a
+.Dq T
+character separates the date and time.
+.It $((Time)(ISO8601B))
+Specifies the local timezone and ISO 8601 basic format, in the form:
+.Dq "yyyymmddThhmmss[+|-]HH[:MM]" .
+.It $((Time)(ISO8601Z))
+Specifies UTC/Zulu time and ISO 8601 extended format, in the form:
+.Dq "yyyy-mm-ddThh:mm:ssZ" .
+.It $((Time)(ISO8601BZ))
+Specifies UTC/Zulu time and ISO 8601 basic format, in the form:
+.Dq "yyyymmddThhmmssZ" .
.It $((Time)([+|-]HH[:MM]))
Specifies an offset (+ or -) of the indicated number of hours (HH) and optionally minutes (MM) to UTC.
The value is formatted as a string of the form
-.Dq "yyyy-mm-dd hh:mm:ss[+|-]HH:MM" .
+.Dq "yyyy-mm-dd hh:mm:ss[+|-]HH[:MM]" .
+Minutes in the timezone offset are only printed if they are non-zero.
.El
.Pp
+Each of the print formats listed above for Time values may optionally be followed by a dot character and an integer value.
+In that case, sub-second time values will be printed.
+For example, the following line prints messages with a UTC time format, and includes 6 digits of sub-second time:
+.Pp
+.Dl syslog -F '$((Time)(utc.6)) $Host $(Sender)[$(PID)] <$((Level)(str))>: $Message
+.Pp
If a custom format is not being used to specify the format for Time values, then Time values
are generally converted to local time, except when the
.Fl F Ar raw
.Dq J
is interpreted as the local timezone and printed in the same format,
but without a trailing timezone letter.
+.It JZ
+is interpreted as the local timezone and printed with the format
+.Dl yyyy-mm-dd hh:mm:ss[+|-]HH[:MM] .
+The trailing
+.Dq [+|-]HH[:MM]
+string represents the local timezone offset from UTC in hours,
+or in hours and minutes if minutes are non-zero.
+.It ISO8601
+Times are printed with the format specified by ISO 8601:
+.Dl yyyy-mm-ddThh:mm:ss[+|-]HH[:MM] .
+This is the same as the
+.Dq JZ
+format, except a
+.Dq T character separates the date and time components.
.It [+|-]hh[:mm]
The specified offset is used to adjust time.
.El
.Pp
+Each of the time formats above may optionally be followed by a dot character and an integer value.
+In that case, sub-second time values will be printed.
+For example:
+.Pp
+.Dl syslog -T bsd.3
+.Pp
The
.Fl u
option is a short form for
may be one of the following:
.Pp
.Bl -tag -width "safe"
-.It vis
-The default encoding described above.
.It safe
+This is the default encoding for
+.Nm syslog
+output.
Encodes backspace characters as ^H.
Carriage returns are mapped to newlines.
A tab character is appended after newlines so that message text is indented.
+.It vis
+The C-style backslash encoding similar to that produced by the
+.Dq vis -c
+command, as described above.
.It none
No encoding is used.
.El
.Dq none
options may be garbled or subject to manipulation through the use of control characters and control sequences
embedded in user-supplied message text.
-The default
+The
.Dq vis
encoding should be used to view messages if there is any suspicion
that message text may have been used to manipulate the printed representation.
The
.Fl c
option may be used to control filtering.
-In addition to the internal filter value that processes may set as described above,
+In addition to the internal filter mask value that processes may set as described above,
the system maintains a global
.Dq master
-filter.
+filter mask.
This filter is normally
.Dq 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.
+If a value is set for the master filter mask, it overrides the local filter mask for all processes.
+Root user access is required to set the master filter mask value.
.Pp
The current setting of the master filter mask may be inspected using:
.Pp
The character
.Dq x
may be used for Error, as it is used for sending messages.
-The master filter may be unset with:
+The master filter mask may be deactivated with:
.Pp
.Dl syslog -c 0 off
.Pp
-Since it is common to use the filter as a
+Since it is common to use the filter mask as a
.Dq cutoff
mechanism, for example to cut off messages with Debug and Info priority,
a single character from the list above may be specified, preceded by a minus sign.
uses a filter mask starting at level 0 (Emergency)
.Dq 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:
+For example, to set the master filter mask to cause all processes to log messages from Emergency up to Debug:
.Pp
.Dl syslog -c 0 -d
.Pp
-While the master filter level may be set to control the messages produced by all processes,
+While the master filter mask 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
be sent to syslogd using the
.Fl config
flag (without an ``='' character).
-For example, to temporarily disable the message-per-second limit:
+For example, to temporarily disable the kernel message-per-second limit:
.Pp
.Dl syslog -config mps_limit 0
.Pp
will cause
.Nm syslogd
to reset its configuration.
+.Ss ASL OUTPUT MODULES
+ASL Output Modules are named configuration bundles used by the ASL server
+.Nm syslogd ,
+and by the ASL filesystem manager
+.Nm aslmanager .
+The /etc/asl.conf file represents the system's primary output module,
+and is given the name
+.Dq com.apple.asl .
+Other modules are read from files in the /etc/asl directory.
+File names serve as module names.
+ASL Output Modules are described in detail in
+.Xr asl.conf 5 .
+.Pp
+When invoked with
+.Fl module ,
+.Nm syslog
+prints a summary of all loaded ASL Output Modules.
+The summary includes the output files and ASL store directories used by each module,
+a list of the module's configuration rules, and the module's current enabled or disabled status.
+.Fl module Ar name
+prints a summary for the module with the given name.
+.Pp
+ASL Output Modules may be enabled or disabled using the command:
+.Pp
+ syslog -module
+.Ar name
+enable
+.Op 0
+.Pp
+Note that only the superuser (root) may enable or disable a module.
+.Pp
+The name '*'
+(including the single-quote characters)
+may be used to change the status of all ASL Output Modules,
+excluding the primary com.apple.asl module.
+com.apple.asl may be enabled or disabled, but only specifically by name.
+.Pp
+If a module includes rotated files, the command:
+.Pp
+ syslog -module
+.Ar name
+checkpoint
+.Op file
+.Pp
+Will force the module to checkpoint all of its rotated files,
+or just the single optionally named file.
+The name '*'
+(including the single-quote characters)
+may be used to force checkpointing of all rotated files for all ASL Output Modules,
+including the primary com.apple.asl module.
+.Pp
+Note that only the superuser (root) may force files to be checkpointed.
+.Pp
+The checkpoint action sends a command to
+.Nm syslogd
+and waits for a reply to be returned.
+This means that any files currently in use will be checkpointed when the
+.Nm syslog
+command completes.
.Sh SEE ALSO
.Xr syslogd 8 ,
.Xr logger 1 ,
projects / apple / syslog.git / blobdiff