chtag — Change file tag information

Description

chtag allows you to set, modify, remove, or display information in a file tag. A file tag is composed of a text flag (txtflag) and a coded character set:

codeset

Represents the coded character set in which text data is encoded. The code set can be used for uniformly encoded text files or files that contain mixed text/binary data.

txtflag

Indicates whether or not a file contains uniformly encoded or non-uniformly encoded text data.

txtflag = ON indicates the file has uniformly encoded text data
txtflag = OFF indicates the file has non-uniformly encoded text data

Only files with txtflag = ON and a valid code set are candidates for automatic conversion. If txtflag = OFF and a code set is associated with it, automatic conversion will not take effect. However, user applications can take advantage of the associated code set information and perform code set conversion by themselves.

For information about enabling automatic conversion, see the section on using enhanced ASCII functionality in z/OS UNIX System Services Planning.

Options

–b

Indicates that the file contains only binary (non-uniformly encoded) data. Automatic conversion is disabled with this option.

–b is mutually exclusive with the –c, –m, –t, or –r options.

–c codeset

Allows the user to modify the coded character set associated with the file. codeset can be a code set name known to the system or the numeric coded character set identifier (CCSID). If a code set name exists, the numeric CCSID associated with that name is used. –c is mutually exclusive with the –r and –b options. Note that the command iconv -l lists existing CCSIDs along with their corresponding code set names.

Modifying the code set associated with an untagged file without specifying -t causes the file to be marked as "mixed".

–h

Does not change file tag information if the file is a symbolic link or an external link.

–m

Indicates that the file contains mixed text and binary data. The data is not uniformly encoded, but to identify the encoding of portions of the file that are text, this option allows the specifications of a code set with the –c option. This option sets txtflag = OFF. When used without –c, the existing coded character set that is associated with the file is retained.

Automatic conversion is disabled with this option. However, user applications can independently convert any text data residing in the file by knowing the code set associated with it. –m is mutually exclusive with the –b, –t and –r options.

Specifying -m without -c on an untagged file will not have any effect on the tagging of the file.

–p

Prints file tag information associated with a file. If a code set name is not associated with the numeric CCSID in the file tag, the numeric CCSID is presented instead.

The following example is a sample of the output you might see:

t   IBM-1047    T=on    file1
-   untagged    T=on    file2
b   binary      T=off   file3
m   ISO-8859-1  T=off   file4
-   untagged    T=off   file5
b   binary      T=on    file6

where:

t

Text

b

Binary

m

Mixed

Note: Code sets that are aliases of each other exist, which might cause the test to fail because the file inquiry operator might return an alias of the code set you are testing.

–q

Suppresses warning messages.

–r

Removes any tagging information associated with the file and sets the status of the file to "untagged". This option disables automatic conversion for the files. –r is mutually exclusive with the –b, –c, –m, and –t options.

–R

Recursively changes the file tag information. For each pathname operand that names a directory, chtag changes the file tag information about all of the files in the file hierarchy below it. When –h is not specified, and symbolic links (or external links) are specified or encountered during the file hierarchy traversal, the links are followed, and the resolved file (or files in the directory) are changed.

–t

Indicates that the specified file contains pure (uniformly encoded) text data. Used alone, this option sets txtflag = ON and retains the existing coded character set associated with the file. To set or change the code set, use the –c option. Files that are tagged with this option and contain a valid code set are candidates for automatic conversion. –t is mutually exclusive with the –b, –m, and –r options.

–v

Gives verbose output. Displays what state the file tag is currently in, and what state the user is trying to change it to. This option is only useful for the –t, –b, –m, –r and –c options. Output will be displayed in the following format:

txtflag  Char Set  Char Set ---> txtflag  Char Set  Char Set  Filename
         Name      Type                   Name      Type

If a code set name is not associated with the numeric CCSID in the file tag, the numeric CCSID is presented instead. The following example is a sample of the output you might see:

chtag -mvc IBM-1047 file3.c
t   ISO-8859  A --->  m  IBM-1047 E file3.c

where:

A

ASCII

E

EBCDIC

?

Unknown

Usage notes

1. Table 1 illustrates how the different combinations of txtflag and coded character set / CCSID affect a file's candidacy for automatic conversion. txtflag indicates whether this field is turned ON, OFF, binary or untagged. Coded character set / CCSID indicates whether the stored coded character set is valid, invalid, or does not exist. Candidate for automatic conversion indicates whether this file is a candidate for automatic conversion.

   Table 1. Possible txtflag / CCSID combinations

   txtflag	Coded character set / CCSID	Candidate for automatic conversion
   t (on)	Defined	Yes (text file)
   t (off)	Defined	No
   b (off)	––	No
   m (off)	Defined	No (mixed data)
   –– (off)	––	No

2. The tagging of the following files is ignored:
   • /dev/null
   • /dev/random
   • /dev/urandom
   • /dev/zero
   

Exit values

0

Successful completion

1

chtag failed to change the tag of a specified file for the following reasons:

• Calling process does not have appropriate privileges to change file attributes
• An invalid txtflag / coded character set combination was issued

2

Incorrect command line syntax

Related information

iconv, ls