'\" te
.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH bart_rules 4 "9 Sep 2003" "SunOS 5.11" "File Formats"
.SH NAME
bart_rules \- bart rules file
.SH DESCRIPTION
.sp
.LP
The \fBbart_rules\fR file is a text file that is used by the \fBbart\fR(1M)
command. The rules file determines which files to validate and which file
attributes of those files to ignore.
.sp
.LP
Some lines are ignored by the manifest comparison tool. Ignored lines include
blank lines, lines that consist only of white space, and comments that begin
with \fB#\fR.
.sp
.LP
The rules file supports three directives: \fBCHECK\fR, \fBIGNORE\fR, and a
\fIsubtree\fR directive, which is an absolute path name and optional pattern
matching modifiers. Each \fBCHECK\fR, \fBIGNORE\fR, and \fIsubtree\fR directive
must be on a separate line. Bart supports continuation of long lines using a
backslash (\fB\e\fR). The rules file uses the directives to create logical
blocks.
.SS "Syntax"
.sp
.LP
The syntax for the rules file is as follows:
.sp
.in +2
.nf
[IGNORE \fIattribute\fR...]*
[CHECK] [\fIattribute\fR...]*

\fIsubtree1\fR [\fIpattern\fR...]*
[IGNORE \fIattribute\fR...]*
[CHECK] [\fIattribute\fR...]*

\fIsubtree2\fR [\fIpattern\fR...]*
\fIsubtree3\fR [\fIpattern\fR...]*
\fIsubtree4\fR [\fIpattern\fR...]*
[IGNORE \fIattribute\fR...]*
[CHECK] [\fIattribute\fR...]*
\&...
.fi
.in -2

.SS "Rule Blocks"
.sp
.LP
Rule blocks are composed of statements that are created by using directives and
arguments.
.sp
.LP
There are three types of blocks:
.sp
.ne 2
.mk
.na
\fBGlobal Block\fR
.ad
.RS 16n
.rt  
The first block in the file. The block is considered ``global'' if it specifies
\fBCHECK\fR and \fBIGNORE\fR statements, but no previous subtree statement. A
global block pertains to all subsequent blocks.
.RE

.sp
.ne 2
.mk
.na
\fBLocal block\fR
.ad
.RS 16n
.rt  
A block that specifies \fBCHECK\fR and \fBIGNORE\fR statements as well as a
subtree directive. The rules in this block pertain to files and directories
found in the specified subtree.
.RE

.sp
.ne 2
.mk
.na
\fBHeir block\fR
.ad
.RS 16n
.rt  
A block that contains a null \fBCHECK\fR statement, no arguments. This block
inherits the global \fBCHECK\fR statements and \fBIGNORE\fR statements.
.RE

.sp
.LP
The order in which \fBCHECK\fR and \fBIGNORE\fR statements appear in blocks is
important. The \fBbart\fR command processes \fBCHECK\fR and \fBIGNORE\fR
statements in the order in which they are read, with later statements
overriding earlier statements.
.sp
.LP
Subtree specifications must appear one per line. Each specification must begin
with an absolute path name. Optionally, each specification can be followed by
pattern-matching arguments.
.sp
.LP
When a file system being tracked belongs to more than one subtree directive,
\fBbart\fR performs the following resolution steps:
.RS +4
.TP
.ie t \(bu
.el o
Applies the \fBCHECK\fR and \fBIGNORE\fR statements set in the global block.
Note that all \fBCHECK\fR and \fBIGNORE\fR statements are processed in order.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Finds the last subtree directive that matches the file.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Processes the \fBCHECK\fR and \fBIGNORE\fR statements that belong to the last
matching subtree directive. These statements are processed in the order in
which they are read, overriding global settings.
.RE
.SS "Pattern Matching Statements"
.sp
.LP
There are two types of pattern matching statements
.sp
.ne 2
.mk
.na
\fBAND\fR
.ad
.RS 7n
.rt  
For a given subtree directive, all pattern matching statements are logically
ANDed with the subtree. Patterns have the following syntax:
.RS +4
.TP
.ie t \(bu
.el o
Wildcards are permitted for both the subtree and pattern matching statements.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The exclamation point (\fB!\fR) character represents logical NOT.
.RE
.RS +4
.TP
.ie t \(bu
.el o
A pattern that terminates with a slash is a subtree. The absence of a slash
indicates that the pattern is not a directory. The subtree itself does not
require an end slash.
.RE
For example, the following subtree example includes the contents of
\fB/home/nickiso/src\fR except for object files, core files, and all of the
SCCS subtrees. Note that directory names that terminate with \fB\&.o\fR and
directories named \fBcore\fR are \fBnot\fR excluded because the patterns
specified do not terminate with \fB/\fR.
.sp
.in +2
.nf
/home/nickiso/src !*.o !core !SCCS/
CHECK  all
.fi
.in -2

.RE

.sp
.ne 2
.mk
.na
\fBOR\fR
.ad
.RS 7n
.rt  
Group multiple subtree directives together. Such subtree directives are
logically ORed together.
.sp
.in +2
.nf
/home/nickiso/src !*.o !core
/home/nickiso/Mail
/home/nickiso/docs *.sdw
CHECK   all
IGNORE  mtime lnmtime dirmtime
.fi
.in -2

The files included in the previous example are as follows:
.RS +4
.TP
.ie t \(bu
.el o
Everything under \fB/home/nickiso/src\fR except for \fB*.o\fR and \fBcore\fR
files
.RE
.RS +4
.TP
.ie t \(bu
.el o
Everything under \fB/home/nickiso/Mail\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
All files under \fB/home/nickiso/docs\fR that end in \fB*.sdw\fR
.RE
For these files, all attributes are checked except for modification times.
.RE

.SS "File Attributes"
.sp
.LP
The \fBbart\fR command uses \fBCHECK\fR and \fBIGNORE\fR statements to define
which attributes to track or ignore. Each attribute has an associated keyword.
.sp
.LP
The attribute keywords are as follows:
.sp
.ne 2
.mk
.na
\fBacl\fR
.ad
.RS 12n
.rt  
ACL attributes for the file. For a file with ACL attributes, this field
contains the output from \fBacltotext()\fR.
.RE

.sp
.ne 2
.mk
.na
\fBall\fR
.ad
.RS 12n
.rt  
All attributes.
.RE

.sp
.ne 2
.mk
.na
\fBcontents\fR
.ad
.RS 12n
.rt  
Checksum value of the file. This attribute is only specified for regular files.
If you turn off context checking or if checksums cannot be computed, the value
of this field is \fB-\fR.
.RE

.sp
.ne 2
.mk
.na
\fBdest\fR
.ad
.RS 12n
.rt  
Destination of a symbolic link.
.RE

.sp
.ne 2
.mk
.na
\fBdevnode\fR
.ad
.RS 12n
.rt  
Value of the device node. This attribute is for character device files and
block device files only.
.RE

.sp
.ne 2
.mk
.na
\fBdirmtime\fR
.ad
.RS 12n
.rt  
Modification time in seconds since 00:00:00 UTC, January 1, 1970 for
directories.
.RE

.sp
.ne 2
.mk
.na
\fBgid\fR
.ad
.RS 12n
.rt  
Numerical group ID of the owner of this entry.
.RE

.sp
.ne 2
.mk
.na
\fBlnmtime\fR
.ad
.RS 12n
.rt  
Creation time for links.
.RE

.sp
.ne 2
.mk
.na
\fBmode\fR
.ad
.RS 12n
.rt  
Octal number that represents the permissions of the file.
.RE

.sp
.ne 2
.mk
.na
\fBmtime\fR
.ad
.RS 12n
.rt  
Modification time in seconds since 00:00:00 UTC, January 1, 1970 for files.
.RE

.sp
.ne 2
.mk
.na
\fBsize\fR
.ad
.RS 12n
.rt  
File size in bytes.
.RE

.sp
.ne 2
.mk
.na
\fBtype\fR
.ad
.RS 12n
.rt  
Type of file.
.RE

.sp
.ne 2
.mk
.na
\fBuid\fR
.ad
.RS 12n
.rt  
Numerical user ID of the owner of this entry.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRSample Rules File
.sp
.LP
The following is a sample rules file:

.sp
.in +2
.nf
# Global rules, track everything except dirmtime.
CHECK   all
IGNORE  dirmtime

# The files in /data* are expected to change, so don't bother
# tracking the attributes expected to change.
# Furthermore, by specifying ``IGNORE contents,'' you save
# time and resources.
/data*
IGNORE  contents mtime size

/home/nickiso f* bar/
IGNORE  acl

# For /usr, apply the global rules.
/usr
CHECK

# Note: Since /usr/tmp follows the /usr block, the /usr/tmp
# subtree is subjected to the ``IGNORE all.''
/usr/tmp
/home/nickiso *.o
/home/nickiso core
/home/nickiso/proto
IGNORE  all
.fi
.in -2

.sp
.LP
The following files are cataloged based on the sample rules file:

.RS +4
.TP
.ie t \(bu
.el o
All attributes, except for \fBdirmtime\fR, \fBmtime\fR, \fBsize\fR, and
\fBcontents\fR, are tracked for files under the \fB/data*\fR subtrees.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Files under the \fB/usr\fR subtree, except for \fB/usr/tmp\fR, are cataloged by
using the global rules.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If the \fB/home/nickiso/foo.c\fR file exists, its attributes, except for
\fBacl\fR and \fBdirmtime\fR, are cataloged.
.RE
.RS +4
.TP
.ie t \(bu
.el o
All \fB\&.o\fR and \fBcore\fR files under \fB/home/nickiso\fR, as well as the
\fB/home/nickiso/proto\fR and \fB/usr/tmp\fR subtrees, are ignored.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If the \fB/home/nickiso/bar/foo.o\fR file exists, it is ignored because it is
subject to the last block.
.RE
.SH SEE ALSO
.sp
.LP
\fBbart\fR(1M), \fBbart_manifest\fR(4), \fBattributes\fR(5)