cc.magic, default.magic
File-typing rules
Applicability
Product |
Command type |
---|---|
VersionVault |
data structure |
Platform |
---|
UNIX® |
Linux® |
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 VersionVault uses 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® and Linux® 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.)
On Windows®, VersionVault 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 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
VersionVault supports
a search path for magic files. If MAGIC_PATH is set in your environment (to a colon-separated list
of directories (UNIX® and Linux®) or to a -separated list of directories (Windows®)), xversionvault
or VersionVault 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® and Linux®) home-directory/.magic:${versionvault-home-dir:–/opt/hcl/ccm/versionvault}/config/magic
(Windows®) home-directory\.magic;versionvault-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.
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 an example for UNIX® or Linux® 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, xversionvault
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
General information about 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 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® or Linux® dynamic views only
When an xversionvault
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 fail when applied by a VersionVault browser in a VOB directory:
text_file : -printable ; file : ! -printable ;
- This rule fails when applied by a VersionVault browser in a VOB directory, because the
–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 VersionVault 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® or Linux® file.On UNIX® and Linux® 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.
xversionvault
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).
Table
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® and Linux®)
- Matches an object if the leading characters in its file(1) command output match the specified double-quoted string.
- –file_re regex (UNIX® and Linux®)
- Matches an object if all the characters in its file(1) command output match the specified double-quoted regular expression.
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 |
! -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® and Linux® 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
versionvault-home-dir/config/magic/default.magic
See also
cc.icon, default.icon, file(1), mkelem, mkeltype, stat(2), wildcards_ccase