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:
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" ;
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:
Each file-typing rule has the following format:
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.
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:
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:
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.
A selection expression consists of one or more selection operators and their arguments, connected by logical operators. Examples:
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:
- This rule always fails when applied by a ClearCase or ClearCase LT browser in a VOB directory, because –magic is invalid:
- 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:
- –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).
- 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.
- Its first block must contain only characters evaluating to TRUE by the X/Open isprint and isspace routines.
- –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
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 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|
- Assign the file types source_file and text_file to files whose file name extension is .c or .h.
- Assign the file types cplspls_source and text_file to printable files whose file name extension is .cxx or .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.
- Assign the file type directory to all directory objects.
- Assign the file types cpio and file to objects that the standard UNIX file(1) programs reports as cpio archive.
- Assign the file types doc_file and text_file to printable files with the file name extension .txt or .doc.