cc.magic, default.magic

File-typing rules

APPLICABILITY

Product	Command type
ClearCase	data structure
ClearCase LT	data structure

Platform
UNIX
Windows

SYNOPSIS

File-typing rule:
file-type-list : selection-expression ;
File-type list:
file-type [ file-type ... ]

Selection expression:
selection-op [ arg(s) ] [ logical-op selection-op [ arg(s) ] ] ...

DESCRIPTION

A magic file contains an ordered set of file-typing rules, which ClearCase and ClearCase LT use to determine a list of file types for an existing file system object or for one that is about to be created. (For information about predefined element types, see the mkeltype reference page.) A rule can use the object's name, its file(1) or stat(2) data, or its contents. File-typing involves searching one or more magic files for the first rule that matches a file system object. Finding a match yields a single file type or an ordered list of file types; failing to find a match produces an error.

On UNIX systems, file-typing is performed in the following situations:

When you create a new element with mkelem, but do not specify an element type (with –eltype), the element's name is file-typed. (If you are converting a view-private file to an element with mkelem –ci or mkelem –nco, the file's contents are also used in the file-typing.) The resulting file type list is compared with the VOB's set of element types (which includes both element types in the VOB and element types in the administrative VOB hierarchy associated with the VOB). The first file type that matches an element type is chosen as the element type; if no file type matches any existing element type, an error occurs:
The file browsers have a graphical mode, in which each file system object is displayed as an icon. The icon is selected first by file-typing the object, and then using one of its file types to select a bitmap from the ones listed in an icon file. (See the cc.icon reference page.)

Note: In an MVFS directory (any directory accessed through a VOB tag), file-typing by a browser uses only a file's name and its stat data; for performance reasons, the file's contents are not used.

On Windows, ClearCase and ClearCase LT perform file-typing when you create a new element with mkelem, but do not specify an element type (with –eltype). (If you are converting a view-private file to an element with mkelem –ci or mkelem –nco, the file's contents are also used in the file-typing.) The resulting file type list is compared to the VOB's set of element types (which includes both element types in the VOB and element types in the administrative VOB hierarchy associated with the VOB). The first file type that matches an element type is chosen as the element type; if no file type matches any existing element type, an error occurs:

cleartool: Error: Can't pick element type from rules ...

Following are examples of file-typing rules:

directory : -stat d ;
c_source source text_file : -printable & -name "*.c" ;
sh_script script text_file : -printable & (-name ".profile" | -name "*.sh") ;
archive library file: !-printable & -name "*.a" ;

Search Path

ClearCase and ClearCase LT support a search path for magic files. If MAGIC_PATH is set in your environment (to a colon-separated list of directories (UNIX) or to a semicolon-separated list of directories (Windows)), xclearcase or ClearCase searches files with a .magic extension in these directories. In each directory, files are processed in alphabetical order. As soon as a matching rule is found, the search ends. If multiple rules match a file type, the first rule encountered is used.

If MAGIC_PATH is not set, this default search path is used:

(UNIX) home-directory/.magic:${ccase-home-dir:–/opt/rational}/config/magic

(Windows) %HOME%\.magic;ccase-home-dir\config\magic

FILE-TYPING RULES

Each file-typing rule has the following format:

file-type-list : selection-expression ;

A single text line can contain multiple rules. Conversely, a single rule can span several lines; each intermediate line must end with a backslash (\). A line that begins with a number sign (#) is a comment.

Note: The semicolon (;) that terminates a rule must be separated from the preceding characters by white space.

FILE-TYPE LIST

A file-type list is an ordered list of one or more names, separated by white space. Only letters, digits, and underscores ( _ ) are permitted in these names. Depending on the file-typing situation, each name must match either an element type defined in some VOB or an icon name specified in an icon file. To avoid errors, always make the final name one of the predefined element types (see the mkeltype reference page). These names are also included in the system-default icon file.

Following are some file-type list examples:

text_file
backup_dir directory
manual_page text_file
cplusplus_src src_file text_file

Here is a UNIX system scenario that calls for a lengthy file-type list:

Your host mounts several VOBs, in which different sets of element types are defined. Perhaps one VOB defines element type bshell for Bourne shell scripts, a second VOB defines element type shell_script for all shell scripts, and a third VOB does not define any special element type for scripts. Your file-typing rules must be appropriate for all the VOBs. For example:

bshell shell_script text_file : -name "*.sh" ;
shell_script text_file : -name "*.csh" ;

Following these file-typing rules, xclearcase uses the file type text_file to select the same icon for all shell script files. A user who wants to distinguish Bourne shell scripts from C shell scripts can add a cshell file type and create different bitmaps to correspond to the unique file types bshell and cshell.

Magic file:

bshell shell_script text_file : -name "*.sh" ;
cshell shell_script text_file : -name "*.csh" ;

Icon file:

bshell : -icon bourne_shell_icon ;
cshell : -icon C_shell_icon ;

SELECTION EXPRESSION

A selection expression consists of one or more selection operators and their arguments, connected by logical operators. Examples:

-name "*.c"
-name "*.[ch]"
-name "*.c" | -name "*.h"
-printable
!-printable
-stat d

Selection Operators and Arguments—General Information

Any abbreviation of a selection operator name is accepted. For example, you can abbreviate –name to –n, –na, or –nam.

All string arguments must be enclosed in double quotes. Use \” to include a double-quote character in a string argument.

If the file system object exists, any of the selection operators listed below can produce a match. If you are determining the file type for a nonexistent object (for example, an element that is about to be created with mkelem), only the –name operator can produce a match.

Selection Operators and Arguments—UNIX Dynamic Views Only

When an xclearcase browser performs file-typing in an MVFS directory to determine which icons to display, only the –name and –stat operators can produce a match. All other operators are invalid; expressions derived from the invalid operations with logical NOT and logical AND are also invalid and can never produce a match. Examples:

Both of the following rules always fail when applied by a ClearCase or ClearCase LT browser in a VOB directory:
```
text_file : -printable ;
file : ! -printable ;
```
This rule always fails when applied by a ClearCase or ClearCase LT browser in a VOB directory, because –magic is invalid:
```
xyz_file : -magic 0, "<xyz>" & -name "*.xyz" ;
```
When applied by a browser in a VOB directory, the subexpression before the logical OR never produces a match, but the subexpression after the logical OR can produce a match, making the entire expression TRUE:
```
bourne_shell : (-magic 0, "#!/bin/sh" & -stat f) | -name "*.sh"
```

–name pattern

Matches an object's simple file name (leaf name) against pattern. pattern is a double-quoted string and can include any ClearCase or ClearCase LT wildcard, except the ellipsis (...). See the wildcards_ccase reference page for a complete list.

–stat stat_char

Matches an object against the specified stat file type. stat_char is a single character:

r	Regular file
d	Directory
c	Character device; not supported for Windows files
b	Block device; not supported for Windows files
f	FIFO (named pipe); not supported for Windows files
s	Socket; not supported for Windows files
l	Symbolic link

Note: The types c, b, f, and s can be used on Windows if they are pointed at a UNIX file.

On UNIX systems, the selection expression –stat l & –stat r is TRUE for a symbolic link that points to a regular file. But testing for symbolic links is not particularly useful. xclearcase displays an icon for the object it finds at the end of a chain of symbolic links.

–magic byte_offset, data_type, value –magic byte_offset, string

Matches an object against a magic value: a number or string at a specified offset within the object's first physical block (512 bytes).

byte_offset	The byte offset from the beginning of the file.
data_type	The architecture-specific data format of the numeric value argument that follows:
	byte	value is an 8-bit byte.
	l_short	value is a little-endian 16-bit shortword.
	l_long	value is a little-endian 32-bit longword.
	b_short	value is a big-endian 16-bit shortword.
	b_long	value is a big-endian 32-bit longword.
value	A numeric magic value, expressed as an integer in hexadecimal, octal, or decimal:
	0x ...	A hexadecimal value
	0 ...	An octal value
	...	(Any other form) A decimal value
string	A nonnumeric magic value, expressed as a double-quoted string.

–printable

Matches an object if it is a printable file:

Its first block must contain only characters evaluating to TRUE by the X/Open isprint and isspace routines.
Its first block must have an average line length <= 256

Remember that mkelem can create an element object that corresponds to an empty (and therefore unprintable) file.

–token string

Matches an object if the specified double-quoted string occurs in its first physical block (512 bytes).

–file string (UNIX only)

Matches an object if the leading characters in its file(1) command output match the specified double-quoted string.

Logical Operators

File-typing rules can use the following logical operators, listed in decreasing order of precedence:

(0)	Parentheses for grouping
!	Unary NOT
&	Logical AND
&&	Logical AND
\|	Logical OR
\|\|	Logical OR

Note: The effect of the unary NOT operator may depend on whether an object exists. It cannot produce a match if the selection operator is inappropriate. For example, on UNIX systems, attempting to get the file status of a nonexistent object:

`! -stat f`	Produces a match when file-typing the name of an existing directory
`! -stat f`	Fails to produce a match when file-typing a name for which no object currently exists

EXAMPLES

Assign the file types source_file and text_file to files whose file name extension is .c or .h.
```
source_file text_file : -name "*.c" | -name "*.h" ;
```
Assign the file types cplspls_source and text_file to printable files whose file name extension is .cxx or .c++.
```
cplspls_source text_file : -printable & (-name "*.cxx" | -name "*.c++") ;
```
Assign the file types csh_script and text_file to printable files that begin with the character string #! and whose first block contains the string csh.
```
csh_script text_file : -printable & -magic 0,"#!" & -token "csh" ;
```
Assign the file type directory to all directory objects.
```
directory : -stat d ;
```
Assign the file types cpio and file to objects that the standard UNIX file(1) programs reports as cpio archive.
```
cpio file : -file "cpio archive" ;
```
Assign the file types doc_file and text_file to printable files with the file name extension .txt or .doc.
```
doc_file text_file : -printable & (-name "*.doc" | -name "*.txt");
```

FILES

ccase-home-dir/config/magic/default.magic