10697N/A<!
DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [
10697N/A<!--ArborText, Inc., 1988-1999, v.4002-->
10697N/A<!
ENTITY suncopy "Copyright (c) 2003,2004, Sun Microsystems, Inc. All Rights Reserved.">
17617N/A<
refentrytitle>&cmd;</
refentrytitle><
manvolnum>1</
manvolnum>
10697N/A<
refmiscinfo class="date">16 Apr 2007</
refmiscinfo>
10697N/A<
refmiscinfo class="sectdesc">&man1;</
refmiscinfo>
10697N/A<
refmiscinfo class="software">&release;</
refmiscinfo>
10697N/A<
refmiscinfo class="arch">generic</
refmiscinfo>
10697N/A<
refmiscinfo class="copyright">&suncopy;</
refmiscinfo>
17617N/A<
primary>Examine encoding of a file name or content and convert to UTF-8</
primary>
17617N/A<
refpurpose>Examine encoding of a file name or content and convert to UTF-8</
refpurpose>
10697N/A<
refsynopsisdiv id="fsexam-1-synp"><
title>&synp-tt;</
title>
10697N/A<
cmdsynopsis><
command>&clicmd;</
command>
10697N/A<
arg choice="opt"><
option role="nodash">-a</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-b</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-d <
replaceable>dry-run-result-file</
replaceable></
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-E <
replaceable>module-name</
replaceable></
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-e <
replaceable>encoding-list</
replaceable></
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-F</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-f <
replaceable>'expression'</
replaceable></
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-g <
replaceable>history-length</
replaceable></
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-H</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-k</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-L <
replaceable>log-file</
replaceable></
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-l</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-n</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-P</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-p</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-R</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-r</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-S</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-s</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-t</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-w</
option></
arg>
10697N/A<
cmdsynopsis><
command>&clicmd;</
command>
10697N/A<
arg choice="opt"><
option role="nodash">-V</
option></
arg>
10697N/A<
cmdsynopsis><
command>&clicmd;</
command>
10697N/A<
arg choice="opt"><
option role="nodash">-?</
option></
arg>
10697N/A<
cmdsynopsis><
command>&cmd;</
command>
10697N/A<
arg choice="opt"><
option role="nodash">-a</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-b</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-E <
replaceable>module-name</
replaceable></
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-e <
replaceable>encoding-list</
replaceable></
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-F</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-f <
replaceable>'expression'</
replaceable></
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-g <
replaceable>history-length</
replaceable></
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-H</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-k</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-L <
replaceable>log-file</
replaceable></
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-l</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-n</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-P</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-p</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-R</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-r</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-S</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-s</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-t</
option></
arg>
10697N/A<
arg choice="opt"><
option role="nodash">-w</
option></
arg>
10697N/A<
cmdsynopsis><
command>&cmd;</
command>
10697N/A<
arg choice="opt"><
option role="nodash">-V</
option></
arg>
10697N/A<
cmdsynopsis><
command>&cmd;</
command>
10697N/A<
arg choice="opt"><
option role="nodash">-?</
option></
arg>
10697N/A<
refsect1 id="fsexam-1-desc"><
title>&desc-tt;</
title>
17617N/AThe <
command>&cmd;</
command> graphical user interface utility examines file
17617N/Anames or file contents and try to convert them from legacy encodings to UTF-8
17617N/Ausing given encoding list, system default encoding list, or both.
17617N/AThe <
command>&clicmd</
command> invocation is the same as
17617N/A<
command>&cmd;</
command> except that the utility is now a command line
17617N/AWhen converting file names, <
command>&cmd;</
command> will process regular file
17617N/Anames, directory file names, and symbolic links by default. When converting
17617N/Afile content, it will handle regular plain text files only by default. Use
17617N/A"<
option>E</
option> <
replaceable>module-name</
replaceable>" to enable
17617N/A<
command>&cmd;</
command> will ignore most of non-plain text files such as
17617N/Abinary files, office document files, image files, and so on. It might produce
17617N/Aunexpected results if conversion of such files are forced with the
17617N/A<
option>F</
option> option. Internally, <
command>&cmd;</
command> uses the
17617N/A<
citerefentry><
refentrytitle>file</
refentrytitle>
17617N/A<
manvolnum>1</
manvolnum></
citerefentry>
17617N/Autility to determine whether files are plain text files or not.
17617N/ABy default, <
command>&cmd</
command> will convert file names. To convert file
17617N/Acontents instead, specify the <
option>t</
option> option.
17617N/ATo help find the best encoding, <
command>&cmd;</
command> has encoding lists for
17617N/Asupported languages. They include the most popular codesets or encodings of
17617N/Acorresponding languages. For example, <
command>&cmd;</
command> specifies
17617N/AGB18030, BIG5, EUC-TW, and so on for Simplified Chinese. The list is used to
17617N/Agenerate conversion candidates. You can use the
17617N/A"<
option>e</
option> <
replaceable>encoding-list</
replaceable>" option
17617N/Ato add more encodings other than those system predefined encodings. If the
17617N/A<
option>a</
option> option is specified, additional encodings that are suggested
17617N/Aby the encoding auto-detection library will be added to the encoding list for
17617N/Apossible use. The encoding specified by the <
option>e</
option> option has
17617N/Ahigher priority than the automatically detected encodings.
10697N/A<
refsect1 id="fsexam-1-opts"><
title>&opts-tt;</
title>
17617N/AThe following options are supported:
17617N/A<
variablelist termlength="wholeline">
10697N/A<
term><
option role="nodash">-a </
option></
term>
10697N/A<
term><
option>-auto-detect</
option></
term>
17617N/AEnable encoding auto-detection. <
command>&cmd;</
command> can guess the
17617N/Aencodings of file names or file contents with the help of encoding
17617N/Aauto-detection library interfaces. Use this option when you do not know the
17617N/Aencodings of files. Note that in file name conversions, the auto-detection
17617N/Abased on the statistics may not be reliable due to small number of characters
10697N/A<
term><
option role="nodash">-b</
option></
term>
10697N/A<
term><
option>-batch</
option></
term>
17617N/ABatch mode which is also known as non-interactive mode. With this mode, <
command>&cmd;</
command>
17617N/Awill not display candidates or wait for user's selection or confirmation.
17617N/APlease make sure your terminal can display UTF-8 characters well when using
17617N/Athis option. Otherwise, illegible or gibberish characters may be presented to
10697N/A<
term><
option role="nodash">-d <
replaceable>dry-run-result-file</
replaceable></
option></
term>
17617N/ASpecifies the dry run result file. Used with <
option>n</
option> option, the dry
17617N/Arun result will be stored into the file. Used without the <
option>n</
option>
17617N/Aoption, <
command>&cmd;</
command> will convert based on the scenario in the dry
17617N/AThe dry run result file will be created if it does not exist. If it exists as a
17617N/Aregular file, the file will be truncated to zero length and overwritten.
17617N/AWhen <
command>&cmd;</
command> creates a dry run result file, you can edit and
17617N/Athen subsequently feed it to <
command>&cmd;</
command> to perform conversions
17617N/Abased on the content of the edited dry run result file. Note that the editing
17617N/Ashould be done carefully in the format preserving manner. Recommended edit
17617N/Aoperation is to delete any wrong or inappropriate candidates and make the right
17617N/Aone as the first candidate. For more information, refer to
17617N/A<
citerefentry><
refentrytitle>fsexam</
refentrytitle>
17617N/A<
manvolnum>4</
manvolnum></
citerefentry>.
17617N/AIf the edited file does not conform to the file format described in the
17617N/A<
citerefentry><
refentrytitle>fsexam</
refentrytitle>
17617N/A<
manvolnum>4</
manvolnum></
citerefentry>, then <
command>&cmd;</
command> will
17617N/Aprint out a warning message and quit without doing anything.
17617N/A<
term><
option role="nodash">-E <
replaceable>module-name</
replaceable></
option></
term>
17617N/A<
term><
option>-enable-module <
replaceable>module-name</
replaceable></
option></
term>
17617N/AEnable special file handling. Currently the only valid option argument is
17617N/A"COMPRESS". "ALL" can be used to enable all modules
17617N/AThe COMPRESS module supports several popular compress and archive format files.
17617N/Aformats. Used with the <
option>t</
option> option, <
command>&cmd;</
command>
17617N/Aconverts contents of files in archived, compressed, or files of both. Without
17617N/Athe <
option>t</
option> option, <
command>&cmd;</
command> converts file names.
17617N/ANote that the COMPRESS module ignores symbolic links in the files archived,
17617N/Acompressed, or both. It also ignores the <
option>n</
option> option. The
17617N/ACOMPRESS module handles files compressed, archived, or both only if the
17617N/A<
option>R</
option> option is specified. If there is no suitable ISO8859-1
17617N/Acodeset locales in the system, this option is not supported as described in the
10697N/A<
term><
option role="nodash">-e <
replaceable>encoding-list</
replaceable></
option></
term>
10697N/A<
term><
option>-encoding-list <
replaceable>encoding-list</
replaceable></
option></
term>
17617N/ASpecifies one or more colon or comma separated encodings to be used during
17617N/AIf this or <
option>a</
option> options are not specified,
17617N/A<
command>&cmd;</
command> uses system pre-defined encoding list for the current
17617N/AIf specified without the <
option>a</
option>, <
option>p</
option>, or
17617N/A<
option>P</
option> options, by default, the list of encodings supplied with
17617N/Athe <
option>e</
option> option replaces the system pre-defined encoding list for
17617N/AUse <
option>p</
option> to prepend it after the system pre-defined encoding
17617N/Alist. Use <
option>P</
option> to append it before the pre-defined encoding
17617N/Alist. If you want to make the encoding-list permanent, instead of only for the
17617N/Acurrent session, use the <
option>S</
option> option.
17617N/AWhen used with the <
option>a</
option> option, <
command>&cmd;</
command> will
17617N/Amerge the supplied encoding list and auto-detected encoding list. Note that the
17617N/Asupplied encoding-list here has higher priority than the auto-detected
17617N/AIn non-interactive mode, the first encoding which can be used to convert file
17617N/Aname or file content to UTF-8 successfully is used. In interactive mode,
17617N/A<
command>&cmd;</
command> will display all candidates that are successfully
17617N/Aconverted from the encodings in the list of encodings to UTF-8. Note that if
17617N/A<
command>&cmd;</
command> cannot convert successfully, such encodings will not
17617N/Abe displayed in the list of candidates.
10697N/A<
term><
option role="nodash">-F</
option></
term>
10697N/A<
term><
option>-force-convert</
option></
term>
17617N/AForcible conversion mode. <
command>&cmd;</
command> will determine whether file
17617N/Aname or file content is in UTF-8 or not. If it is in UTF-8 already, then,
17617N/A<
command>&cmd;</
command> will not convert by default. However, since
17617N/A<
command>&cmd;</
command> has no completely accurate way to determine whether a
17617N/Astring is in UTF-8 or not, sometimes, a byte sequence in legacy encoding could
17617N/Abe treated as a valid UTF-8 string. As an example, three Simplified Chinese
17617N/Acharacters in GB2312 (two bytes per character) could be treated as two valid
17617N/AUTF-8 characters (three bytes per character). Use this option to bypass the
17617N/Averification step and perform conversions forcibly.
17617N/AThis option has to be used with caution and you should avoid using it with the
17617N/A<
option>R</
option> option whenever possible. It may convert real UTF-8 encoded
17617N/Afile names or file contents to unintended characters.
10697N/A<
term><
option role="nodash">-f <
replaceable>'expression'</
replaceable></
option></
term>
10697N/A<
term><
option>-find-expression <
replaceable>'expression'</
replaceable></
option></
term>
17617N/ASearch files according to <
replaceable>'expression</
replaceable>'. The
17617N/A<
replaceable>'expression'</
replaceable> here is a subset of the
17617N/A<
replaceable>'expression'</
replaceable> used in
17617N/A<
citerefentry><
refentrytitle>file</
refentrytitle>
17617N/A<
manvolnum>1</
manvolnum></
citerefentry>.
17617N/A<
citerefentry><
refentrytitle>file</
refentrytitle>
17617N/A<
manvolnum>1</
manvolnum></
citerefentry>,
17617N/Athe <
replaceable>'expression'</
replaceable> here must include a path name of a
17617N/Astarting point in the directory hierarchy in which you want to search files
17617N/Afrom as the first item. Following the path name, other items valid for the
17617N/Aexpression are the following options and their combinations:
17617N/A<
option>name</
option>, <
option>amin</
option>, <
option>atime</
option>,
17617N/A<
option>cmin</
option>, <
option>ctime</
option>, <
option>group</
option>,
17617N/A<
option>mmin</
option>, <
option>mtime</
option>, and <
option>user</
option>.
17617N/A<
citerefentry><
refentrytitle>file</
refentrytitle>
17617N/A<
manvolnum>1</
manvolnum></
citerefentry>,
17617N/Afor more information. Internally, <
command>&cmd;</
command> uses
17617N/A<
citerefentry><
refentrytitle>file</
refentrytitle>
17617N/A<
manvolnum>1</
manvolnum></
citerefentry>,
17617N/AYou may want to use single quote to quote the whole expression because shell
17617N/Amay expand special characters in it if you use double quotes.
10697N/AWhen this option is used, any other operands are ignored.
17617N/A<
term><
option>g <
replaceable>history-length</
replaceable></
option></
term>
17617N/ASet the history length. <
command>&cmd;</
command> saves the information about on
17617N/Awhat it has done and use the information to handle restore operations.
17617N/ABy default, <
command>&cmd;</
command> will save history information for 100
17617N/A<
command>&cmd;</
command> executions as long as disk space permits. A single
17617N/Abatch conversion counts as one. Use this option to change the default value.
17617N/AIf you change the length from a higher value to a lower value, the older
17617N/Ahistory information will be purged.
17617N/AWhen the number of history reach to the top limit, <
command>&cmd;</
command>
17617N/Awill discard the oldest history information in order to accept and record new
10697N/A<
term><
option role="nodash">-H</
option></
term>
10697N/A<
term><
option>-hidden</
option></
term>
17617N/AHandles hidden files. Unless the option is specified, hidden files with names
17617N/Astarting with a dot (.) will be ignored by default.
10697N/A<
term><
option role="nodash">-k</
option></
term>
10697N/A<
term><
option>-no-check-symlink-content</
option></
term>
17617N/ABy default, during file name conversions, if both symbolic link and its source
17617N/Abelong to the user supplied list of files or a starting point of a directory
17617N/Ahierarchy at operands, <
command>&cmd;</
command> tries to keep them consistent.
17617N/AIn other words, if a source name is converted, then, not only symbolic link
17617N/Aitself when applicable but also the content of the symbolic link is converted.
17617N/AIf given source names are not converted for some reason, the corresponding
17617N/Asymbolic link contents are also not converted and warning messages are issued.
17617N/AIf either is not in the operand specified list, <
command>&cmd;</
command> may
17617N/AThis default behavior of symbolic link processings need more resource and
17617N/Acomputation time and thus use of -k option is recommended to bypass the default
17617N/Abehavior of symbolic link processing if you have no symbolic links.
17617N/ADuring content conversions and dry run conversions, <
command>&cmd;</
command>
17617N/Adoes not care about the symbolic link contents.
10697N/A<
term><
option role="nodash">-l</
option></
term>
13723N/A<
term><
option role="nodash">-list-encoding</
option></
term>
17617N/AList all available encodings supported by <
command>&cmd;</
command>.
10697N/A<
term><
option role="nodash">-L <
replaceable>log-file</
replaceable></
option></
term>
10697N/A<
term><
option>-log-file <
replaceable>log-file</
replaceable></
option></
term>
17617N/AIf specified, <
command>&cmd;</
command> writes log into the
17617N/A<
replaceable>log-file</
replaceable>. Default is no log file writing.
17617N/AThe "category" values possible are "ERROR"
17617N/A"WARNING" and "INFO" The "fullpath" is the full
17617N/Apath of file that is handled. The "message" briefly describes the
17617N/AIf the "fullpath" or the "message" contain non-UTF-8
17617N/Acharacters, <
command>&cmd;</
command> writes their hexadecimal byte values
17617N/Aprefixed with "x" such as "xAE\\x89" into the file.
10697N/A<
term><
option role="nodash">-n</
option></
term>
10697N/A<
term><
option>-dry-run</
option></
term>
17617N/ADry run mode. With this mode, <
command>&cmd;</
command> writes conversion
17617N/Ainformation into the dry-run-result-file specified with the <
option>d</
option>
17617N/Aoption instead of actually performing the conversion on the file names or
17617N/AIf used with the <
option>a</
option> option, the dry-run-result-file may get
17617N/ANote that compressed or archived files are not supported with this mode and
17617N/Asymbolic links and their source consistencies are also not kept.
10697N/A<
term><
option role="nodash">-P</
option></
term>
10697N/A<
term><
option>-append-encoding-list</
option></
term>
17617N/AWhen used with the <
option>e</
option> option, <
command>&cmd;</
command> appends
17617N/Athe encoding-list to the system pre-defined encoding list. Otherwise, it has no
17617N/A</
para></
listitem></
varlistentry>
10697N/A<
term><
option role="nodash">-p</
option></
term>
10697N/A<
term><
option>-prepend-encoding-list</
option></
term>
17617N/AWhen used with the <
option>e</
option> option, <
command>&cmd;</
command> prepends
17617N/Athe encoding-list to the system pre-defined encoding list. Otherwise, it has no
10697N/A<
term><
option role="nodash">-R</
option></
term>
10697N/A<
term><
option>-recursive</
option></
term>
17617N/ARecursive mode. In this mode, <
command>&cmd;</
command> recursively converts all
17617N/Aapplicable files and subdirectories specified at the operands as directories.
10697N/A<
term><
option role="nodash">-r</
option></
term>
10697N/A<
term><
option>-remote</
option></
term>
17617N/AWith this option, <
command>&cmd;</
command> handles files mounted as NFS and
17617N/Asuch remote file systems. Without the option, <
command>&cmd;</
command> handles
17617N/AObviously, while <
command>&cmd;</
command> is running, mounting or unmounting
17617N/Aa file system in the directory hierarchy that is being examined is not
10697N/A<
term><
option role="nodash">-S</
option></
term>
10697N/A<
term><
option>-save-encoding-list</
option></
term>
17617N/ABy default, the encoding-list option argument of the <
option>e</
option> option
17617N/Ais used only for the current session. If this option is specified, however,
17617N/A<
command>&cmd;</
command> makes the encoding-list option argument permanent.
17617N/AThis option may override the default, system pre-defined encoding list. If you
17617N/Ado not want that to happen, use with <
option>p</
option> or <
option>P</
option>
17617N/Ato prepend or append, respectively.
10697N/A<
term><
option role="nodash">-s</
option></
term>
10697N/A<
term><
option>-restore</
option></
term>
17617N/ARestores file names to their original names. To restore file contents, specify
17617N/Awith the <
option>t</
option> option.
17617N/AThis option is useful when you want to restore files to their last states in
17617N/Acase wrong conversions have been made.
17617N/AWhen this option is used on a file, <
command>&cmd;</
command> restores its name
17617N/Aor content. When used on a directory together with the <
option>R</
option>
17617N/Aoption, <
command>&cmd;</
command> restores all files and subdirectories under
17617N/Athe directory including the directory to their original names or contents.
17617N/A</
para></
listitem></
varlistentry>
10697N/A<
term><
option role="nodash">-t</
option></
term>
10697N/A<
term><
option>-conv-content</
option></
term>
17617N/AConverts file contents rather than file names. <
command>&cmd;</
command> mainly
17617N/AInternally, <
command>&cmd;</
command> uses
17617N/A<
citerefentry><
refentrytitle>file</
refentrytitle>
17617N/A<
manvolnum>1</
manvolnum></
citerefentry>.
17617N/Ato determine whether a file is a plain text file or not.
17617N/AFirst convert file names before converting contents if there are files or
17617N/Adirectories that contain multi-byte characters in their files names. Otherwise,
17617N/Ayou may get illegible characters in your log-file or dry-run-result-file.
10697N/A<
term><
option role="nodash">-w</
option></
term>
10697N/A<
term><
option>-follow</
option></
term>
17617N/AIf specified with the <
option>R</
option> option, <
command>&cmd;</
command>
17617N/Afollows symbolic links if they are symbolic links to directories as if they
17617N/Awere regular and normal directories. If no <
option>R</
option> option is
17617N/Aspecified, <
command>&cmd;</
command> tries to convert symbolic links and it
17617N/Asource only. If the source is a symbolic link too, <
command>&cmd;</
command>
17617N/Akeep convert source's source and so on. By default, <
command>&cmd;</
command>
10697N/A<
term><
option role="nodash">-V</
option></
term>
10697N/A<
term><
option>-version</
option></
term>
17617N/ADisplay version information of <
command>&cmd;</
command> and exit.
10697N/A<
term><
option role="nodash">-?</
option></
term>
10697N/A<
term><
option>-help</
option></
term>
17617N/ADisplay usage information and exit.
17617N/A</
para></
listitem></
varlistentry>
10697N/A<
refsect1 id="fsexam-1-operands"><
title>OPERANDS</
title>
17617N/AThe following operand is supported:
10697N/A<
variablelist termlength="narrow">
10697N/A<
varlistentry><
term><
option role="nodash">pathname </
option></
term><
listitem>
17617N/AThe pathname of a file or a directory to be converted. All arguments behind
17617N/A"--" will be treated as an operand, even if they begin with '-'
17617N/Acharacter. If <
command>&cmd;</
command> encounters '-' as an operand or no
17617N/Aoperand at all, <
command>&cmd;</
command> will read pathnames from the standard
10697N/A<
refsect1 id="fsexam-1-exam"><
title>&exam-tt;</
title>
10697N/A<
title>Convert the name of a file</
filename></
title>
17617N/AThe following will convert the name of file "myfile" using the system
17617N/A<
userinput>example% <
command>&cmd;</
command> myfile</
userinput>
17617N/AIf there is no pre-defined encoding for the current locale,
17617N/A<
command>&cmd;</
command> will exit with error messages.
10697N/A<
title>Recursively convert the names of files and subdirectories under
17617N/Athe directory "mydir" with the given encoding list</
title>
17617N/A<
userinput>example% <
command>&cmd;</
command> -e GB18030:BIG5:EUC-TW --recursive mydir</
userinput>
17617N/A<
title>Dry run <
command>&cmd;</
command> with auto-detected encoding </
title>
17617N/AThe following will scan the directory "mydir" and try to convert file
17617N/Aand directory names under the directory with the system pre-defined plus
17617N/Aauto-detected encodings to UTF-8 and store the result into the file,
17617N/A"mydryrunresult" without actually changing the names:
17617N/A<
userinput>example% <
command>&cmd;</
command> --auto-detect --dry-run -d mydryrunresult \\
17617N/A<
title>Perform scenario based conversions using a dry run result file</
title>
17617N/AThe following will perform scenario based conversions by using the
17617N/A"mydryrunresult". The first candidate for each file name is used. If
10697N/Athere is no candidate, no action will be taken on the file:
17617N/A<
userinput>example% <
command>&cmd;</
command> -d mydryrunresult</
userinput>
17617N/A<
title>Forcibly convert a file name</
title>
17617N/AThe following will convert the file "myfile" by using the system
17617N/Apre-defined encodings even if <
command>&cmd;</
command> thinks it is UTF-8
17617N/Aencoding already. This option should be used with caution as it may corrupt
17617N/Athe already UTF-8 file names and contents:
17617N/A<
userinput>example% <
command>&cmd;</
command> --force myfile</
userinput>
10697N/A<
title>Convert files generated by other utility
17617N/AThe following two examples have the same effect and it will convert files
17617N/A<
citerefentry><
refentrytitle>find</
refentrytitle>
17617N/A<
manvolnum>1</
manvolnum></
citerefentry>
17617N/Acommand with the system pre-defined and auto-detected encodings:
17617N/A<
userinput>example% /
usr/
bin/
find . -name "*.txt" | <
command>&cmd;</
command> --auto-detect</
userinput>
17617N/A<
userinput>example% <
command>&cmd;</
command> --auto-detect `/
usr/
bin/
find . -name "*.txt"`</
userinput>
17617N/AThe following is similar to the above two examples except the following uses
17617N/Athe system pre-defined encodings only and files generated by the
17617N/A<
citerefentry><
refentrytitle>ls</
refentrytitle>
17617N/A<
manvolnum>1</
manvolnum></
citerefentry>
17617N/A<
userinput>example% /
usr/
bin/
ls *.txt | <
command>&cmd;</
command> </
userinput>
17617N/AThe following will search all files trailing with '.txt' under the current
17617N/Adirectory and convert any of them using the system pre-defined encoding list:
17617N/A<
userinput>example% <
command>&cmd;</
command> -f '. -name "*.txt"'</
userinput>
10697N/A<
title>Batch mode conversion</
title>
17617N/AThe following will use GB18030 and BIG5 to recursively convert file names under
17617N/Athe directory "mydir" and use the first candidate to convert the file
17617N/A<
userinput>example% <
command>&cmd;</
command> --batch -e GB18030:BIG5 --recursive mydir</
userinput>
10697N/A<
title>Follow symbolic links and handle hidden files
17617N/AThe following will follow all symbolic links in the directory "mydir"
17617N/Aand symbolic links in the symbolic link source's directory. Hidden files under
10697N/Athe directory will be converted also:
17617N/A<
userinput>example% <
command>&cmd;</
command> --follow --hidden --recursive mydir
17617N/A<
title>Convert file contents recursively using specified encoding list</
title>
17617N/AThe following will recursively scan files under the directory
17617N/A"mydir". For each plain text file, it will automatically detect its
17617N/Apossible encodings, combine them with GB18030 or BIG5, and try to convert the
17617N/Afile using the encodings formulated one by one. If the conversion is
17617N/Asuccessful, <
command>&cmd;</
command> is done with the file and rest of the
17617N/Aencodings will not be tried. If a file is a compressed or archived file,
17617N/A<
command>&cmd;</
command> will first uncompress and unarchive them into a
17617N/Atemporary directory and perform above operation, compress and archive them
17617N/Aagain, and replace the original file:
17617N/A<
userinput>example% <
command>&cmd;</
command> --conv-content --recursive -e GB18030:BIG5 \\
10697N/A--auto-detect --enable-module COMPRESS mydir
10697N/A<
title>Restore a file name or a file content
17617N/AThe following restores the file "myfile" to its original name:
17617N/A<
userinput>example% <
command>&cmd;</
command> --restore myfile</
userinput>
17617N/A<
userinput>example% <
command>&cmd;</
command> --conv-content --restore myfile</
userinput>
17617N/AThe following restores the content of "myfile" to its original
10697N/A<
refsect1 id="fsexam-1-exit"><
title>&exit-tt;</
title>
17617N/AThe following exit values are returned:
10697N/A<
variablelist termlength="xtranarrow">
17617N/A<
term><
returnvalue>0</
returnvalue></
term>
17617N/AFile names or contents are converted successfully or corresponding information
17617N/Ais written to a dry run result file successfully.
17617N/A</
para></
listitem></
varlistentry>
10697N/A<
term><
returnvalue>\>0</
returnvalue></
term>
17617N/AAn error occurred. More information can be retrieved from a log file if
17617N/A"<
option>L</
option> <
replaceable>log-file</
replaceable>" option and
17617N/A</
para></
listitem></
varlistentry>
10697N/A<
refsect1 id="fsexam-1-attr"><
title>&attr-tt;</
title>
17617N/A<
olink targetdocent="REFMAN5" localinfo="attributes-5">
17617N/A<
citerefentry><
refentrytitle>attributes</
refentrytitle>
17617N/A<
manvolnum>5</
manvolnum></
citerefentry></
olink>
17617N/Afor descriptions of the following attributes:
17617N/A<
tgroup cols="2" colsep="1" rowsep="1">
17617N/A<
colspec colname="COLSPEC0" colwidth="1*">
10697N/A<
colspec colname="COLSPEC1" colwidth="1*">
17617N/A<
entry align="center" valign="middle">ATTRIBUTE TYPE</
entry>
17617N/A<
entry align="center" valign="middle">ATTRIBUTE VALUE</
entry>
17617N/A<
entry><
para>Availability</
para></
entry>
17617N/A<
entry colname="COLSPEC0"><
para>Interface stability</
para></
entry>
17617N/A<
entry colname="COLSPEC1"><
para>Committed</
para></
entry>
10697N/A<
refsect1 id="fsexam-1-also"><
title>&also-tt;</
title>
10697N/A<!--Reference to another man page--> 10697N/A<!--Reference to a Help manual--> 17617N/A<
citerefentry><
refentrytitle>file</
refentrytitle><
manvolnum>1</
manvolnum></
citerefentry>,
17617N/A<
citerefentry><
refentrytitle>find</
refentrytitle><
manvolnum>1</
manvolnum></
citerefentry>,
17617N/A<
citerefentry><
refentrytitle>locale</
refentrytitle><
manvolnum>1</
manvolnum></
citerefentry>,
17617N/A<
citerefentry><
refentrytitle>ls</
refentrytitle><
manvolnum>1</
manvolnum></
citerefentry>,
17617N/A<
citerefentry><
refentrytitle>tar</
refentrytitle><
manvolnum>1</
manvolnum></
citerefentry>,
17617N/A<
citerefentry><
refentrytitle>libauto_ef</
refentrytitle><
manvolnum>3LIB</
manvolnum></
citerefentry>,
17617N/A<
citerefentry><
refentrytitle>fsexam</
refentrytitle><
manvolnum>4</
manvolnum></
citerefentry>
17617N/A<
citerefentry><
refentrytitle>attributes</
refentrytitle><
manvolnum>5</
manvolnum></
citerefentry>
10697N/A<
refsect1 id="fsexam-1-notes"><
title>¬e-tt;</
title>
17617N/AWhen you want to convert names of many files, do not convert them one by one in
17617N/Aa loop. Try to construct a list of files and give the list to
17617N/A<
command>&cmd;</
command> for conversions. For example, the following is not
17617N/AIt is highly recommended to run this utility with UTF-8 locale. Otherwise, you
17617N/Amay see some illegible or garbled characters. Since <
command>&cmd;</
command>
17617N/Ahas the system pre-defined and the most popular encodings for every language,
10697N/Aconsidering the best multiscript capability, it will be more smooth if
10697N/Ayou run on a UTF-8 locale environment of your language.
17617N/AAs shown in the NOTES section of the
17617N/A<
citerefentry><
refentrytitle>tar</
refentrytitle>
17617N/A<
manvolnum>4</
manvolnum></
citerefentry>
17617N/Aman page, if an archive is created that contains files whose names were created
17617N/Aby processes running in multiple or different locales, a locale that uses a
17617N/Aused both to create the archive and to extract files from the archive. Due to
17617N/Athat, when you specify COMPRESS module with <
option>E</
option> option,
17617N/AIf there is no such locale in the current system, use of <
option>E</
option>
17617N/Aoption is ignored and a warning message is issued.