dtdtsfile

special file

`dtdtsfile`

format and location of desktop data type and action files

    set DtDbVersion=version_number
    set VariableName=variable_value
    RecordType record_name
    {
            # Comment
            FieldName field_value
            FieldName field_value
            ...
    }

## DESCRIPTION

The &str-XZ; data types database provides definitions for the data types and actions recognized by &str-XZ; 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 blanks following the \ and preceding the newline are discarded; leading blanks 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 &cdeman.dtaction; 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 &cdeman.DtDtsBufferToDataType; 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:

`string`

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

`byte`

short

long

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

`filename`

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

`d`

- match a directory

`s`

- match a socket

`l`

- match a symbolic link

`f`

- match a regular file

`b`

- match a block file

`c`

- match a character special file

The first, or subsequent characters, can also be:

`r`

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

`w`

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

`x`

- 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 `sh`(1)
`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 blanks (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 &str-Zx; 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.

1. Records are ordered by the fields specified within them:

   1. Records with both content and pattern fields (most specific)

   2. Records with only pattern fields

   3. Records with only content fields

   4. Records with neither content nor pattern fields (least specific)

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

   1. File names with no shell pattern-matching characters (most specific)

   2. File names with no shell pattern-matching characters in the final suffix (such as `*.c`)

   3. Others (least specific)

3. Records with a path pattern are more specific than records with a name pattern.

4. Records with a name pattern of `*` are treated as if they have no name pattern.

5. Records are ordered based on the types of shell pattern-matching characters in their patterns:

   1. Patterns with any `?` (most specific)

   2. Patterns with any `[]`

   3. Patterns with any `*` (least specific)

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

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

   2. The selected paths are ordered so that the longest is more specific.

   3. 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:

      1. Path patterns with fewer `*` characters are more specific.

      2. Path patterns with fewer `[]` characters are more specific.

      3. Path patterns with fewer `?` characters are more specific.

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

7. Records are ordered based on a character sorting of the path patterns, with the lowest value in collation sequence being more specific.

8. 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 &str-XZ; 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 &str-XZ; 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 &str-XZ; 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 widget--even binary data can be--but 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 &str-XZ; 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 &str-XZ; 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 &str-XZ; 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:

`%file%`

- The full pathname of the file.

`%dir%`

- The directory component of the pathname. For example, for `/usr/src/file.c`, `%dir%` is `/usr/src`.

`%name%`

- The filename of the file. For example, for `/usr/src/file.c`, `%name%` is `file.c`.

`%suffix%`

- The suffix of the file. For example, for `/usr/src/file.c`, `%suffix%` is `c`.

`%base%`

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

&cdeman.dttypes;, &cdeman.DtDtsIsTrue;, &cdeman.dtdtfile;, &cdeman.dtactionfile;.