dtdtsfile(4)

NAME
dtdtsfile - format and location of desktop data type and action files

SYNOPSIS
set DtDbVersion=version_number
set VariableName=variable_value

RecordType record_name
{
	# Comment
	FieldName field_value
	FieldName field_value
		.
		.
		.
}

DESCRIPTION
The CDE data types database provides definitions for the data types and actions recognized by CDE clients.

The general syntax of the data types files is as described above in the SYNOPSIS section of this man page. The set of general constructs composing the database entries is as follows:

  Comments
Any line whose first non-space character is # is treated as a comment line, and is ignored during the reading of the database file.

  Database Version
The database loader supports a version number, which indicates the version of the database syntax used by a particular database file. If a database version number is not specified, then the database loader assumes that the file uses the version 1.0 syntax, described here. If a database file specifies a version number, then it must be the first non-blank, non-comment line in the database file; if the version is specified anywhere else in the file, then an error message is generated, and the remainder of that database file is ignored. The database version number is specified using the following syntax:

    set DtDbVersion=version_number

  String Variables
Database records can reference string variables that are set within the database file. The scope of a string variable is restricted to only those record definitions within the database file defining the string variable. A string variable is defined using the following syntax:

    set VariableName=variable_value

String variables are referenced using either of the standard shell variable referencing syntaxes: $variable_name or ${variable_name}. A variable name can be made up of any of the alphanumeric characters and the underscore.

  Environment Variables
Database records may refer to environment variables, using either of the standard shell variable referencing syntaxes: $environment_variable or ${environment_variable}. If the environment variable name conflicts with a string variable name, the string variable takes precedence.

  Line Continuation
Any field within a record can be continued onto another line by ending the line with a \ character. The \ and any <blank>s following the \ and preceding the newline are discarded; leading <blank>s on the following line are preserved in the continued field.

  Record Name
The first line of a record is made up of the record type, RecordType (one of: DATA_ATTRIBUTES, DATA_CRITERIA or ACTION), followed by the record name, record_name, which is henceforth used to identify this record. The record_name string must be coded in ASCII and must be uniquely named across the data attributes, data criteria and actions tables.

  Record Delimiters
After the record name has been located, the set of corresponding fields is delimited by the { and } characters. Each of these characters must appear on a line by itself.

  Fields
The fields are all of the non-comment lines found between the record delimiters. They are composed of keyword/value pairs. The FieldName string must be coded in ASCII. The field_value may be coded in additional, implementation-dependent, code sets, except that any literal string values shown in Data Criteria Format, below, string must be coded in ASCII.

  Record Types
There are three recognized record types in database files used for data types (and actions):

    DATA_CRITERIA DATA_ATTRIBUTES ACTION

These three kinds of database record can appear together in the same file or they can be segregated into separate files. See dtaction(4) for the file format of ACTION records.

DATA_CRITERIA RECORDS
The first seven subsections of this section describe the FieldName s supported for data criteria records. The remaining subsections describe formatting and sorting information for data criteria records.

  NAME_PATTERN Field
A shell pattern-matching expression describing the file names that could match this data. See Pattern Matching Notation. The default is an empty string, which means to ignore file patterns in matching.

If the data to be matched is in a buffer, rather than a file, the NAME_PATTERN expression is evaluated against the opt_name value given to DtDtsBufferToDataType(3) and related functions.

  PATH_PATTERN Field
A shell pattern-matching expression describing the absolute pathnames that could match this data. See Pattern Matching Notation. The default is an empty string, which means to ignore path patterns in matching.

The PATH_PATTERN expression is used only for matching data in files; it does not affect matching of data in buffers.

  CONTENT Field
Strings that match on the contents of a file, buffer or directory:

    offset type value(s)

The offset string is a positive decimal integer number of octets from the beginning of the file or buffer, where the first value is tested. The offset value is ignored for the filename type.

The type string is one of the following:

    The value is a single string that is compared against the data starting at the offset location.

    Each <blank>-separated value is an unsigned integer: decimal, octal (leading 0) or hexadecimal (leading 0x or 0X). Multiple values are matched against multiple byte (octet), short (two octets) or long (four octets) locations starting at offset octets from the beginning of the file or data. The value is a string that is compared against the filenames located anywhere in a directory. The use of filename on non-directory data produces undefined results.

The default CONTENT is an empty field, which means to ignore contents in matching.

The CONTENT field applies to data in both files and buffers.

Examples of two data criteria records with CONTENT fields are:

    DATA_CRITERIA PCL1
    {
    	DATA_ATTRIBUTES_NAME    PCL
    	CONTENT         0 byte 033 0105
    	MODE            f&!x
    }

    DATA_CRITERIA POSTSCRIPT3
    {
    	DATA_ATTRIBUTES_NAME    POSTSCRIPT
    	CONTENT         0 string %!
    	MODE            f&!x
    }

  MODE Field
A string of zero to four characters that match the mode field of a stat structure (see stat(2)). The first character indicates:

    match a directory match a socket match a symbolic link match a regular file match a block file match a character special file

The first, or subsequent characters, can also be:

    match any file with any of its user, group, or other read permission bits set match any file with any of its user, group, or other write permission bits set match any file with any of its user, group, or other execute or directory-search permission bits set

For example, the MODE field of frw matches any regular file that is readable or writable; x matches any file with any of its executable or search bits set.

The default is an empty field, which means to ignore the mode in matching.

If the data to be matched is in a buffer, rather than a file, the buffer is processed as if it had a mode of fr.

  LINK_NAME Field
A shell pattern-matching expression describing the filename component (basename) of the filename the symbolic link points to that could match this data. See Pattern Matching Notation. The default is an empty expression, which means to ignore symbolic link names in matching. LINK_NAME points to the file itself, not to the name of the file.

The LINK_NAME expression is used only for matching data in files; it does not affect matching of data in buffers.

  LINK_PATH Field
A shell pattern-matching expression describing the absolute pathname of the file pointed to by the symbolic link that could match this data. See Pattern Matching Notation. The default is an empty expression, which means to ignore symbolic link name in matching.

The LINK_PATH expression is used only for matching data in files; it does not affect matching of data in buffers.

  DATA_ATTRIBUTES_NAME Field
The name of this type of data. This value is a record_name in the data attributes table.

  Pattern Matching Notation
The pattern-matching text field permits use of the shell pattern-matching characters *, ?, and []. The asterisk (*) matches any set of characters, the question mark (?) matches a single character, and the square brackets ([]) match any one of a set of characters enclosed in the square brackets. The full definition of shell pattern matching is in the X/Open CAE Specification, Commands and Utilities, Issue 4.

  Logical Expressions
The logical operators AND (&), OR (|) and NOT (!) can be used in any of the data criteria fields, except for DATA_ATTRIBUTES_NAME, as shown in Data Criteria Format, below. The resultant expressions are evaluated from left to right.

  White Space
White space is used to delimit tokens, as shown by the blanks and newline terminals in Data Criteria Format, below. Within the pattern terminal, however, leading and trailing white space not explicitly shown in the grammar is significant to the expression. For example,

    NAME_PATTERN   abc | def

is matched by either ``abc '' (with a trailing <space>) or `` def'' (with a leading <space>).

  Escape Character
Shell pattern-matching and logical expression characters can be escaped and used as literal characters by preceding the character with a backslash (\). For example, \* is interpreted as an asterisk, \? as a question mark and \[\] as square brackets. Backslash itself can be escaped by preceding it with a backslash (\\).

  Data Criteria Format
The following pseudo-BNF describes the data criteria variable definition:

DataCriteriaDefn | ::= | `DATA_CRITERIA' blanks record_name
{
 |  | data_criteria_defn
}
data_criteria_defn | ::= | (
 |  | `PATH_PATTERN' blanks pattern_datas newline
 | | | `NAME_PATTERN' blanks pattern_datas newline
 | | | `LINK_PATH' blanks pattern_datas newline
 | | | `LINK_NAME' blanks pattern_datas newline
 | | | `CONTENT' blanks content_fields newline
 | | | `MODE' blanks mode_specs newline
 | | | `DATA_ATTRIBUTES_NAME' blanks name newline
 |  | )
pattern_datas | ::= | pattern_data [(`&' | `|') pattern_datas]
pattern_data | ::= | [`!'] pattern
pattern | ::= | a shell pattern matching expression, as defined in
mode_specs | ::= | mode_spec [(`&' | `|') mode_specs]
mode_spec | ::= | (
 |  | type_spec [permission_spec]
 | | | type_spec (`&' | `|') permission_spec
 |  | )
type_spec | ::= | [`!'] type_char {type_char}
type_char | ::= | (`d' | `l' | `f' | `s' | `b' | `c' )
permission_spec | ::= | [`!'] permission_char {permission_char}
permission_char | ::= | (`r' | `w' | `x')
content_fields | ::= | content_field [(`&' | `|') content_fields]
content_field | ::= | (
 |  | [`!'] offset blanks `string' blanks string
 | | | [`!'] offset blanks `byte' blanks data_values
 | | | [`!'] offset blanks `short' blanks data_values
 | | | [`!'] offset blanks `long' blanks data_values
 | | | [`!'] offset blanks `filename' blanks string
 |  | )
offset | ::= | an unsigned decimal integer
data_values | ::= | data_value [blanks data_values]
data_value | ::= | an unsigned integer: decimal, octal (leading 0) or hexadecimal (leading 0x or 0X)
name | ::= | ( "A-Z" | "a-z" ) [name_char]
name_char | ::= | { "A-Z" | "a-z" | "0-9" | "-" }
string | ::= | a character string, not including <newline>
newline | ::= | `\n'
blanks | ::= | one or more <blank>s (spaces and/or tabs)

  Data Criteria Sorting
There may be multiple data criteria records that could match a file or data. This subsection describes the sorting process used by the XCDE data typing services. The more specific criteria are sorted toward the top of the list and the more general criteria toward the bottom. The data criteria record selected is the first match found on the resulting sorted list.

The following sorting rules are applied in sequence to each possible pair of data criteria records. If a rule determines that one data criteria record is more specific than another, the two records are positioned in the list so that the more specific comes before the less specific; otherwise, the next rule in sequence is applied.

    Records are ordered by the fields specified within them:

        Records with both content and pattern fields (most specific) Records with only pattern fields Records with only content fields Records with neither content nor pattern fields (least specific)

    Records are ordered based on the presence of any shell pattern-matching characters in their file name patterns (NAME_PATTERN or PATH_PATTERN):

        File names with no shell pattern-matching characters (most specific) File names with no shell pattern-matching characters in the final suffix (such as *.c) Others (least specific)

    Records with a path pattern are more specific than records with a name pattern. Records with a name pattern of * are treated as if they have no name pattern. Records are ordered based on the types of shell pattern-matching characters in their patterns:

        Patterns with any ? (most specific) Patterns with any [] Patterns with any * (least specific)

    Records with path patterns that share leading pathname components are ordered as follows:

        The leading pathname components without shell pattern-matching characters are selected for comparison. (For example, /foo/bar/bam/baz.? and /foo/bar/*/baz are evaluated as /foo/bar/bam and /foo/bar for this rule.) The selected paths are ordered so that the longest is more specific. If the selected paths are equal, the full path patterns are ordered based on the number and types of shell pattern-matching characters in their patterns, in the following sequence:

            Path patterns with fewer * characters are more specific. Path patterns with fewer [] characters are more specific. Path patterns with fewer ? characters are more specific.

        If the path patterns are still of equal specificity, the one with the larger number of literal characters (those not used as shell pattern-matching special characters) in its pattern after the first non-literal character is more specific.

    Records are ordered based on a character sorting of the path patterns, with the lowest value in collation sequence being more specific. Records are ordered so that the one with more criteria is more specific. (For example, a record with a PATH_PATTERN, CONTENT and MODE is more specific than one with only a PATH_PATTERN.)

Two records still equal after executing the preceding rules are ordered in an unspecified sequence.

DATA_ATTRIBUTES RECORDS
The following FieldNames are supported for data attribute records. Each of the FieldNames is identical to the corresponding name member string of a DtDtsAttribute structure; see <Dt/Dts.h>.

  DESCRIPTION Field
A textual description of the data that is suitable for presentation to a user requesting information about the data. The description should contain no formatting information such as tab or newline characters. The application that presents the information to the user formats the information. If this field is NULL or is not included in the data attribute record, the name of the data attribute should be used.

  ICON Field
The name of the icon to use for this data. If this field is NULL or is not included in the data attribute record, a default value (Dtactn for an executable file or Dtdata for other data) should be used.

Icons are found by using the standard CDE icon search path, so the value can be either an absolute pathname (for example, /foo/icons/myicon.bm), a relative pathname (for example, icons/myicon.bm) or a partial filename (for example, myicon). Partial filenames are preferred because they allow the CDE icon search path to find the icon with the optimum size and depth for the current environment.

  INSTANCE_ICON Field
The name of the icon to use for this instance of data. The contents of this field are as described in ICON Field, above. If INSTANCE_ICON is set, the application should use it instead of ICON. If this field is NULL or is not included in the data attribute record, the ICON field should be used.

An example value of INSTANCE_ICON is %name%.icon, which would select an icon based on a specific filename, rather than on a generic data type.

  PROPERTIES Field
Keywords to indicate properties for this data. Valid values are visible and invisible. These provide guidance to an application such as a file manager about whether a file should be visibly displayed to the user.

If this field is NULL or is not included in the data attribute record, the visible property should be assumed.

  ACTIONS Field
A comma-separated list of actions that can be performed on this data. This list refers to names in the action table for actions that can be performed on this data. If this field is NULL or is not included in the data attribute record, no action is available.

  NAME_TEMPLATE Field
A string used to create a new file for data of this type. The string is intended to be passed to sprintf(3) with the file name as the single argument. For example: %s.mif. The default is empty. (This field is contrasted with the NAME_PATTERN field of the data criteria table in that the template is used to create a specific file, such as %s.c, whereas the pattern is used to find files, such as *.c).

  IS_EXECUTABLE Field
A string-Boolean value that tells users of this data type that it can be executed as an application. If IS_EXECUTABLE is a true value (as determined by the DtDtsIsTrue() function), the data is executable; if this field is NULL, is not included in the data attribute record or is not true, then the data is considered not executable.

  MOVE_TO_ACTION Field
The name of an action to be invoked when an object is moved to the current object using a drag and drop operation.

The MOVE_TO_ACTION, COPY_TO_ACTION and LINK_TO_ACTION fields cause an action to be invoked with the drop target as the first of the DtActionArg arguments to the DtActionInvoke() function, and the drag sources as the remaining DtActionArg arguments. However, if the drop target is an action itself, it is omitted from the DtActionArg list. For example, using the syntax of the dtaction utility, if objects A and B are dropped onto non-action object C:

    dtaction action-name C A B

If C is an action:

    dtaction action-name A B

  COPY_TO_ACTION Field
The name of an action to be invoked when an object is copied to the current object using a drag and drop operation.

  LINK_TO_ACTION Field
The name of an action to be invoked when an object is linked to the current object using a drag and drop operation.

  IS_TEXT Field
A string-Boolean value that tells users of this data type that it is suitable for manipulation (viewing or editing) in a text editor or text widget. The IS_TEXT field should be set to a true value (as determined by the DtDtsIsTrue() function) if the data is textual in nature and if it should be presented to the user in textual form. Criteria for making this determination include whether the data:

    consists of human language, or is generated and maintained manually, or is usefully viewable and editable in a text editor, or contains no (or only minimal) structuring and formatting information.

If the IS_TEXT field is a true value, this indicates that the data is eligible to be displayed directly by an application. That is, the application can load the data directly into a text editing widget (for example, XmText) instead of invoking an action on the data. An example of this occurs in the CDE mail services: if the first part of a multipart message has IS_TEXT true, then it is displayed in the text area of the message view window. Otherwise, the text area will contain only message headers and the first part of the message will be displayed as an icon in the attachment pane. It is immaterial whether the data can be loaded into an XmText widgeteven binary data can bebut rather whether the data should be loaded into an XmText widget.

Note that the IS_TEXT field differs from the text attribute of the MIME_TYPE field, which is the MIME content-type, as described in RFC 1341. The MIME content-type determines whether the data consists of textual characters or byte values. If the data consists of textual characters and is labelled as text/*, the IS_TEXT field determines whether it is appropriate for the data to be presented to users in textual form.

Examples of common data types include recommendations of the appropriate value of IS_TEXT: Human language encoded in ASCII:

    MIME_TYPE	text/plain
    IS_TEXT	true

Note, however, that not everything that is ASCII should be presented directly to the user. Human language encoded in EUC, JIS, Unicode, or an ISO Latin charset:

    MIME_TYPE	text/plain; charset=XXX
    IS_TEXT	true

CalendarAppointmentAttrs:

    MIME_TYPE	text/plain
    IS_TEXT	false

Calendar appointments should be treated as opaque objects (editable only by the appointment editor) and not shown to the user as text. HTML (HyperText Markup Language):

    MIME_TYPE	text/html
    IS_TEXT	true

PostScript:

    MIME_TYPE	application/postscript
    IS_TEXT	false

C program source (C_SRC):

    MIME_TYPE	text/plain
    IS_TEXT	true

Bitmaps and pixmaps (XBM and XPM):

    MIME_TYPE	text/plain
    IS_TEXT	false

Project or module files for the CDE application building services:

    MIME_TYPE	text/plain
    IS_TEXT	false

Shell scripts:

    MIME_TYPE	text/plain
    IS_TEXT	false

Encoded text produced by uuencode(1):

    MIME_TYPE	text/plain
    IS_TEXT	false

Manual pages:

    MIME_TYPE	text/plain
    IS_TEXT	false

  MEDIA Field
The names in the MEDIA name space describe the form of the data itself. MEDIA names are used as ICCCM selection targets; they are named in the MEDIA field of data type records; and they are used in the type parameter of ToolTalk Media Exchange messages.

The MEDIA name space is a subset of the name space of selection target atoms as defined by the ICCCM. All selection targets that specify a data format are valid MEDIA names, and all valid MEDIA names can be used directly as selection targets. Some selection targets specify an attribute of the selection (for example, LIST_LENGTH) or a side effect to occur (for example, DELETE), rather than a data format. These attribute selection targets are not part of the MEDIA name space.

  MIME_TYPE Field
MEDIA is the CDE internal, unique name for data types. However, other external naming authorities have also established name spaces. MIME (Multipurpose Internet Message Extensions), as described in the referenced MIME RFCs, is one of those external registries, and is the standard type name space for the CDE mail system.

  X400_TYPE Field
X.400 types are similar in structure to the MEDIA type, but are formatted using different rules and have different naming authorities.

  DATA_HOST Attribute
The DATA_HOST attribute is not a field that can be added to the data attributes table when it is in a file, but it may be returned to an application reading attributes from the table. The data typing service adds this attribute automatically to indicate the host system from which the data type was loaded. If this field is NULL or is not included in the data attribute record, the data type was loaded from the local system.

  Modifiers
The following modifiers can be used in the values of the data attributes to modify the runtime values:

    The full pathname of the file. The directory component of the pathname. For example, for /usr/src/file.c, %dir% is /usr/src. The filename of the file. For example, for /usr/src/file.c, %name% is file.c. The suffix of the file. For example, for /usr/src/file.c, %suffix% is c. The basename of the file. For example, for /usr/src/file.c, %base% is file.

Strings enclosed in backquotes (`) are processed with the popen() function and the output replaces the backquotes and string.

  Data Attributes Format
The following pseudo-BNF describes the data attributes variable definition:

DataAttributesDefn | ::= | `DATA_ATTRIBUTES' blanks record_name
{
 |  | data_attributes_defn
}
data_attributes_defn | ::= | (
 |  | `DESCRIPTION' blanks string newline
 | | | `ICON' blanks string newline
 | | | `INSTANCE_ICON' blanks string newline
 | | | `PROPERTIES' blanks string {`,' string} newline
 | | | `ACTIONS' blanks name {`,' name} newline
 | | | `NAME_TEMPLATE' blanks string newline
 | | | `IS_EXECUTABLE' blanks string newline
 | | | `MOVE_TO_ACTION' blanks string newline
 | | | `COPY_TO_ACTION' blanks string newline
 | | | `LINK_TO_ACTION' blanks string newline
 | | | `IS_TEXT' blanks string newline
 | | | `MEDIA' blanks string newline
 | | | `MIME_TYPE' blanks string newline
 | | | `X400_TYPE' blanks string newline
 | | | unique_string blanks string newline
 | | | `#' string newline
 |  | )
string | ::= | a character string, not including <newline>
newline | ::= | `\n'
unique_string | ::= | a uniquely named string for implementation extensions
blanks | ::= | one or more <blank>s (spaces and/or tabs)

  EXAMPLES
The following are examples of data attribute and data criteria entries in the data typing database:

    DATA_ATTRIBUTES C_SRC
    {
            ACTIONS         Open,Make,Print
            ICON            DtdotC
            IS_TEXT         true
            NAME_TEMPLATE   %s.c
            DESCRIPTION     A C_SRC file is a source file in the C \
                            programming language.
    }

    DATA_CRITERIA C_SRC1
    {
            DATA_ATTRIBUTES_NAME C_SRC
            MODE            f
            NAME_PATTERN    *.c
    }

    DATA_ATTRIBUTES POSTSCRIPT
    {
            ACTIONS         Open,Print
            ICON            Dtps
            NAME_TEMPLATE   %s.ps
            MEDIA           POSTSCRIPT
            MIME_TYPE       application/postscript
    }

    DATA_CRITERIA POSTSCRIPT1
    {
            DATA_ATTRIBUTES_NAME POSTSCRIPT
            MODE            fr
            NAME_PATTERN    *.ps
    }

ERRORS
Errors encountered when loading database files are written to the CDE errorlog file. Records containing errors are rejected.

SEE ALSO
dttypes(1), DtDtsIsTrue(3), dtdtfile(4), dtactionfile(4).