cc.magic, default.magic

ClearCase file typing rules

APPLICABILITY

ClearCase (data structure)

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 uses to determine a list of file types for an existing file system object, or for one that is about to be created. A rule can use the object's name, its stat 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.

ClearCase performs 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 with the VOB's set of element types (which includes both element types in the VOB and element types in the Admin 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 supports a search path for magic files. If MAGIC_PATH is set in your environment (to a semicolon-separated list of directories), ClearCase searches files with a .magic extension in these directories. In each directory, files are processed in alphabetical order. As soon as ClearCase finds a matching rule, 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:

%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 ClearCase's predefined element types (see Predefined Element Types in 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 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 pscript for Perl scripts, a second VOB defines element type batch_file 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:

pscript batch_file text_file : -name "*.pl" ;
batch_file text_file : -name "*.bat" ;

Magic File:

pscript batch_file text_file : -name "*.pl" ;
shscript batch_file text_file : -name "*.sh" ;

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

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 already 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.

-name pattern

Matches an object's simple filename (leaf name) against the specified pattern. pattern is a double-quoted string, and can include any ClearCase wildcard, except for 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:

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

-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).

-printable

Matches an object if it is a printable file:

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).

Logical Operators

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

NOTE: The effect of the unary NOT operator may depend on whether or not an object exists. It cannot produce a match if the selection operator is inappropriate.

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 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

SEE ALSO

mkelem, mkeltype, wildcards_ccase