<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [

<!--

Process this file with an XSLT processor: `xsltproc \
-''-nonet /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/\
manpages/docbook.xsl manpage.dbk'.  A manual page
<package>.<section> will be generated.  You may view the
manual page with: nroff -man <package>.<section> | less'.  A
typical entry in a Makefile or Makefile.am is:

DB2MAN=/usr/share/sgml/docbook/stylesheet/xsl/nwalsh/\
manpages/docbook.xsl
XP=xsltproc -''-nonet

manpage.1: manpage.dbk
        $(XP) $(DB2MAN) $<

The xsltproc binary is found in the xsltproc package.  The
XSL files are in docbook-xsl.  Please remember that if you
create the nroff version in one of the debian/rules file
targets (such as build), you will need to include xsltproc
and docbook-xsl in your Build-Depends control field.

-->

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!ENTITY dhfirstname "<firstname>Frédéric</firstname>">
  <!ENTITY dhsurname   "<surname>Boiteux</surname>">

  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY dhdate      "<date>december 20, 2004</date>">

  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
  <!ENTITY dhemail     "<email>fboiteux@calistel.com</email>">
  <!ENTITY dhusername  "Frédéric Boiteux">
  <!ENTITY dhucpackage "<refentrytitle>MKSQUASHFS</refentrytitle>">
  <!ENTITY dhpackage   "mksquashfs">

  <!ENTITY debian      "<productname>Debian</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
]>

<!-- ====================================================================== -->
<refentry lang="fr">
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <!-- <author> -->
<!--       &dhfirstname; -->
<!--       &dhsurname; -->
<!--     </author> -->
    <copyright>
      <year>2005</year>
      <holder>&dhusername;</holder>
    </copyright>
    &dhdate;
  </refentryinfo>

  <!-- ============================================================ -->
  <refmeta>
    &dhucpackage;

    &dhsection;
  </refmeta>

  <!-- ============================================================ -->
  <refnamediv>
    <refname>&dhpackage;</refname>

    <refpurpose>Create or modify a Squash file system</refpurpose>
  </refnamediv>

  <!-- ============================================================ -->
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>&dhpackage;</command>
      <arg><option>-version</option></arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>&dhpackage;</command>
      <arg choice="plain"
        rep="repeat"><replaceable>source</replaceable></arg>
      <arg choice="plain"><replaceable>dest</replaceable></arg>
      <arg><option>options</option></arg>
      <arg><option>-e  <replaceable>list of exclude
            dirs/files</replaceable></option></arg>
      <arg><option>-ef <replaceable>exclude_file</replaceable></option></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <!-- ============================================================ -->
  <refsect1>
    <title>DESCRIPTION</title>

    <para>A squashfs is a compressed read-only file system. Use the
      <command>&dhpackage;</command> program to create a new
      squashed file system, and to append new data to an existing
      squashed file system.</para>

    <para>If a single source directory is specified
      (i.e. <userinput>mksquashfs <replaceable>source</replaceable>
        <replaceable>output_fs</replaceable></userinput>), the
      squashfs filesystem will consist of that directory, with the
      top-level root directory corresponding to the source
      directory.</para>

    <para>If multiple source directories or files are specified,
      <command>&dhpackage;</command> will merge the specified sources
      into a single filesystem, with the root directory containing each
      of the source files/directories.  The name of each directory entry
      will be the basename of the source path.   If more than one source
      entry maps to the same name, the conflicts are named
      <replaceable>xxx</replaceable>_1, <replaceable>xxx</replaceable>_2,
      etc. where <replaceable>xxx</replaceable> is the original
      name. </para>

    <para>The <replaceable>dest</replaceable> argument can either
      be a conventional file or a block device. If the file doesn't
      exist it will be created, if it does exist and a squashfs
      filesystem exists on it, <command>&dhpackage;</command> will
      append.  The <option>-noappend </option>option will write a new
      filesystem irrespective of whether an existing filesystem is
      present.</para>

    <para>There are a large number of options that can be used to
      control the compression in <command>&dhpackage;</command>.  By
      and large the defaults are the most optimum settings and should
      only be changed in exceptional circumstances !</para>

    <para>The <option>-noI</option>, <option>-noD</option> and
      <option>-noF</option> options (also
      <option>-noInodeCompression</option>,
      <option>-noDataCompression</option> and
      <option>-noFragmentCompression</option>) can be used to force
      <command>&dhpackage;</command> to not compress
      inodes/directories, data and fragments respectively.  Giving all
      options generates an uncompressed filesystem.</para>


    <para>By default files in the generated filesystem inherit the UID
      and GID ownership of the original file.  However,
      <command>&dhpackage;</command> provides a number of options
      which can be used to override the ownership:
    </para>

      <itemizedlist>
        <listitem>
	<para>
	 The options <option>-all-root</option> and
            <option>-root-owned</option> (both do exactly the same
            thing) force all file uids/gids in the generated Squashfs
            filesystem to be <literal>root</literal>.  This allows
            root owned filesystems to be built without root access on
            the host machine.</para></listitem>
        <listitem>
          <para>The <option>-force-uid
              <replaceable>uid</replaceable></option> option forces
            all files in the generated Squashfs filesystem to be owned
            by the specified <replaceable>uid</replaceable>.  The uid
            can be specified either by name
            (i.e. <literal>root</literal>) or by
            number.</para></listitem>
        <listitem>
          <para>The <option>-force-gid
              <replaceable>gid</replaceable></option> option forces
            all files in the generated Squashfs filesystem to be group
            owned by the specified <replaceable>gid</replaceable>.
            The gid can be specified either by name
            (i.e. <literal>root</literal>) or by
            number.</para></listitem>
      </itemizedlist>

    <para>The <option>-e</option> and <option>-ef</option> options
      allow files/directories to be specified which are
      excluded from the output filesystem.  The <option>-e</option>
      option takes the exclude files/directories from the command
      line, the <option>-ef</option> option takes the exlude
      files/directories from the specified exclude file, one
      file/directory per line. If an exclude file/directory is
      absolute (i.e. prefixed with <filename>/</filename>,
      <filename>../</filename>, or <filename>./</filename>) the entry
      is treated as absolute, however, if an exclude file/directory
      is relative, it is treated as being relative to each of the
      sources in turn, i.e.
      <userinput>mksquashfs /tmp/source1 source2 output_fs -e ex1 /tmp/source1/ex2 out/ex3</userinput>
      Will generate exclude files
      <filename>/tmp/source1/ex2</filename>,
      <filename>/tmp/source1/ex1</filename>,
      <filename>source2/ex1</filename>,
      <filename>/tmp/source1/out/ex3</filename> and
      <filename>source2/out/ex3</filename>.</para>

    <para>The <option>-e</option> and <option>-ef</option> exclude
      options are usefully used in archiving the entire filesystem,
      where it is wished to avoid archiving
      <filename>/proc</filename>, and the filesystem being generated,
      i.e.
      <userinput>mksquashfs / /tmp/root.sqsh -e proc /tmp/root.sqsh</userinput></para>

    <para>Multiple <option>-ef</option> options can be specified on
      the command line, and the <option>-ef</option>
      option can be used in conjuction with the <option>-e</option>
      option.</para>

    <para>The <option>-info</option> option displays the
      files/directories as they are compressed and added to the
      filesystem.  The original uncompressed size of each file is
      printed, along with <literal>DUPLICATE</literal> if the file is
      a duplicate of a file in the filesystem.</para>

    <para>The <option>-no-exports</option> option doesn't make the
      filesystem exportable via NFS.</para>

    <para>The <option>-no-progress</option> option doesn't display the
      progress bar.</para>

    <para>The <option>-le</option> and <option>-be</option> options
      can be used to force <command>&dhpackage;</command> to generate
      a little endian or big endian filesystem.  Normally
      <command>&dhpackage;</command> will generate a filesystem in the
      host byte order.  Squashfs, for portability, will mount
      different ordered filesystems (i.e. it can mount big endian
      filesystems running on a little endian machine), but these
      options can be used for greater optimisation.</para>
  </refsect1>

  <!-- ============================================================ -->
  <refsect1>
    <title>OPTIONS</title>

    <variablelist>
      <varlistentry>
        <term>
          <option>-version</option>
        </term>
        <listitem>
          <para>print version, licence and copyright message.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-recover
            <replaceable>name</replaceable></option></term>

        <listitem><para>Allows the original filesystem to be recovered
            if Mksquashfs aborts unexpectedly (i.e.  power failure)
            using recovery file <replaceable>name</replaceable>.
            Recovery files are now created when appending to existing
            Squashfs filesystems.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-no-recovery</option></term>
        <listitem><para>don't generate a recovery file</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-info</option></term>
        <listitem><para>print files written to filesystem</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-no-exports</option></term>
        <listitem><para>don't make the filesystem exportable via
        NFS</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-no-progress</option></term>
        <listitem><para>don't display the progress bar</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-no-sparse</option></term>
        <listitem><para>don't detect sparse files</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-b
            <replaceable>block_size</replaceable></option></term>
        <listitem><para>set data block to
            <replaceable>block_size</replaceable>. Default is
            131072 bytes</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-processors
            <replaceable>number</replaceable></option></term>
        <listitem><para>Use <replaceable>number</replaceable>
	processors.  By default will use number of processors
	available</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-read-queue
            <replaceable>size</replaceable></option></term>
        <listitem><para>Set input queue to
	<replaceable>size</replaceable> Mbytes. Default 64
	Mbytes.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-write-queue
            <replaceable>size</replaceable></option></term>
        <listitem><para>Set output queue to
	<replaceable>size</replaceable> Mbytes. Default 512
	Mbytes.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-noI</option> or
          <option>-noInodeCompression</option></term>
        <listitem><para>do not compress inode table</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-noD</option>or
          <option>-noDataCompression</option></term>
        <listitem><para>do not compress data blocks</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-noF</option> or
          <option>-noFragmentCompression</option></term>
        <listitem><para>do not compress fragment blocks</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-no-fragments</option></term>
        <listitem><para>do not use fragments: tells
            <command>&dhpackage;</command> to not generate fragment
            blocks, and rather generate a filesystem similar to a
            Squashfs 1.x filesystem. It will of course still be a
            Squashfs 2.0 filesystem but without fragments, and so it
            won't be mountable on a Squashfs 1.x system.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-always-use-fragments</option></term>
        <listitem><para>use fragment blocks for files larger than
            block size: tells <command>&dhpackage;</command> to
            always generate fragments for files irrespective of the
            file length.  By default only small files less than the
            block size are packed into fragment blocks.  The ends of
            files which do not fit fully into a block, are
            <emphasis>NOT</emphasis> by
            default packed into fragments.  To illustrate this, a 100K
            file has an initial 64K block and a 36K remainder.  This
            36K remainder is not packed into a fragment by default.
            This is because to do so leads to a 10 - 20% drop in
            sequential I/O performance, as a disk head seek is needed
            to seek to the initial file data and another disk seek is
            need to seek to the fragment block. Specify this option if
            you want file remainders to be packed into fragment
            blocks. Doing so may increase the compression obtained
            <emphasis>BUT</emphasis> at the expense of I/O
            speed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-no-duplicates</option></term>
        <listitem><para>do not perform duplicate checking: tells
            <command>&dhpackage;</command> to not check the files
            being added to the filesystem for duplicates.  This can
            result in quicker filesystem generation and appending
            although obviously compression will suffer badly if there
            is a lot of duplicate files.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-noappend</option></term>
        <listitem><para>do not append to existing
            filesystem</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-keep-as-directory</option></term>
        <listitem><para>if one source directory is specified,
            create a root directory containing that directory, rather
            than the contents of the directory</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-root-becomes
            <replaceable>name</replaceable></option></term>
        <listitem><para>when appending source files/directories,
            make the original root become a subdirectory in the new
            root called <replaceable>name</replaceable>, rather than
            adding the new source items to the original root</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-all-root</option> or
          <option>-root-owned</option></term>
        <listitem><para>make all files owned by root</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-force-uid
            <replaceable>uid</replaceable></option></term>
        <listitem><para>set all file uids to
            <replaceable>uid</replaceable></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-force-gid
            <replaceable>gid</replaceable></option></term>
        <listitem><para>set all file gids to
            <replaceable>gid</replaceable></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-le</option></term>
        <listitem><para>create a little endian filesystem</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-be</option></term>
        <listitem><para>create a big endian filesystem</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-nopad</option></term>
        <listitem><para>do not pad filesystem to a multiple of 4Ko.
            This is performed by default to enable the output
            filesystem file to be mounted by loopback, which requires
            files to be a 4K multiple.  If the filesystem is being
            written to a block device, or is to be stored in a
            bootimage, the extra pad bytes are not needed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-check_data</option></term>
        <listitem><para>add checkdata for greater filesystem
            checks</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-sort
            <replaceable>sort_file</replaceable></option></term>
        <listitem><para>sort files according to priorities in
            <replaceable>sort_file</replaceable>.  One file or dir
            with priority per line.  Priority -32768 to 32767, default
            priority 0</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-e <replaceable>list of exclude
              dirs/files</replaceable></option></term>
        <listitem><para>inline list of files / directories to
            exclude</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-ef
            <replaceable>exclude_file</replaceable></option></term>
        <listitem><para>file containing a list of files /
            directories to exclude, one per line</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-wildcards</option></term>
        <listitem><para>Allow extended shell wildcards (globbing) to
  	be used in exclude dirs/files</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-regex</option></term>
        <listitem><para>Allow POSIX regular expressions to be used in
	exclude dirs/files</para></listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <!-- ============================================================ -->
  <refsect1>
    <title>EXAMPLES</title>

    <para>For following examples, take two example directories:
      <itemizedlist>
        <listitem>
          <para>Source directory
            <filename>/home/phillip/test</filename> contains
            <filename>file1</filename>, <filename>file2</filename> and
            <filename>dir1</filename>.</para>
        </listitem>
        <listitem>
          <para> Source directory
            <filename>goodies</filename> contains
            <filename>goodies1</filename>,
            <filename>goodies2</filename> and
            <filename>goodies3</filename>.</para>
        </listitem>
      </itemizedlist>
    </para>

    <refsect2>
      <example id="exemple_1">
        <title></title>
        <screen><userinput>mksquashfs /home/phillip/test output_fs</userinput></screen>
        <para>This will generate a squashfs filesystem with root
          entries <filename>file1</filename>, <filename>file2</filename>
          and <filename>dir1</filename>.</para>
      </example>
    </refsect2>

    <refsect2>
      <example>
        <title></title>
        <screen><userinput>mksquashfs /home/phillip/test goodies output_fs</userinput></screen>
        <para>This will create a squashfs filesystem with the root
          containing entries <filename>test</filename> and
          <filename>goodies</filename> corresponding to the source
          directories <filename>/home/phillip/test</filename> and
          <filename>goodies</filename>.</para>
      </example>
    </refsect2>

    <refsect2>
      <example>
        <title></title>
        <screen><userinput>mksquashfs /home/phillip/test goodies test output_fs</userinput></screen>

        <para>This is the same as the previous example, except a third
          source directory <filename>test</filename> has been
          specified. This conflicts with the first directory named
          <filename>test</filename> and will be renamed
          <filename>test_1</filename>.</para>
        <para>Multiple sources allow filesystems to be generated
          without needing to copy all source files into a common
          directory.  This simplifies creating filesystems.</para>
      </example>
    </refsect2>

    <refsect2>
      <example>
        <title></title>
        <screen><userinput>mksquashfs /home/phillip/test output_fs -keep-as-directory</userinput></screen>

        <para>This is the same as the first example,
          except for <option>-keep-as-directory</option>. This will
          generate a root directory containing directory
          <filename>test</filename>, rather than the
          <filename>test</filename> directory contents
          <filename>file1</filename>, <filename>file2</filename> and
          <filename>dir1</filename>.</para>
      </example>
    </refsect2>
  </refsect1>

  <!-- ============================================================ -->
  <refsect1>
    <title>AUTHORS</title>

    <para>Squashfs was written by <personname>
        <firstname>Phillip</firstname>
        <surname>Lougher</surname>
      </personname>
      <email>plougher@users.sourceforge.net</email>, in Chepstow,
      Wales, UK. If you like the program, or have any problems, then
      please email me, as it's nice to get feedback !</para>

    <para>This manual page was written by &dhusername; &dhemail; for
      the &debian; system (but may be used by others) using the
      <citetitle>SquashFS HOWTO</citetitle> from <author>
        <firstname>Artemiy I.</firstname>
        <surname>Pavlov</surname>
      </author> and squashfs's <filename>README</filename> file.
      Permission is granted to copy, distribute and/or
      modify this document under the terms of the &gnu; General Public
      License, Version 2 any later version published by the Free
      Software Foundation.
    </para>

    <para>
      On Debian systems, the complete text of the &gnu;
      General Public License can be found in
      <filename>/usr/share/common-licenses/GPL</filename>.
    </para>
  </refsect1>
</refentry>
