Provided by: bmap-tools_3.4-2_all bug

NAME

       bmaptool - create block map (bmap) for a file or copy a file using bmap

SYNOPSIS

       bmaptool [--help] [--version] [--quiet] [--debug] <command> [<options>] <args>

DESCRIPTION

       Bmaptool  is a generic tool for creating the block map (bmap) for a file and copying files
       using the block map. The idea is that large files, like raw system  image  files,  can  be
       copied  or  flashed  a  lot faster with bmaptool than with traditional tools, like "dd" or
       "cp".

       Bmaptool supports 2 commands:
         1. copy - copy a file to another file using bmap or flash an image to a block device
         2. create - create a bmap for a file

       Please,      find      full       documentation       for       the       project       at
       https://source.tizen.org/documentation/reference/bmaptool

OPTIONS

       --version
         Print bmaptool version and exit.

       -h, --help
         Print short help text and exit.

       -q, --quiet
         Be quiet, do not print extra information.

       -d, --debug
         Print debugging messages.

COMMANDS

   copy [options] IMAGE DEST
         Copy  file  IMAGE to the destination regular file or block device DEST using bmap. IMAGE
         may either be a local path or an URL. DEST may either be  a  regular  file  or  a  block
         device (only local).

         Unless  the  bmap  file  is  explicitly  specified  with  the  "--bmap" option, bmaptool
         automatically discovers it by looking for a file with the same  basename  as  IMAGE  but
         with  the  ".bmap"  extension. The bmap file is only looked for in IMAGE's directory (or
         base URL, in case IMAGE was specified as an  URL).  If  the  bmap  file  is  not  found,
         bmaptool fails. To copy without bmap, use the "--nobmap" option.

         Both  IMAGE  and  the  bmap  file may be specified as an URL (http://, ftp://, https://,
         file://, ssh://). In order to make bmaptool use a  proxy  server,  please,  specify  the
         proxy  using  the  standard  "$http_proxy",  "$https_proxy", "$ftp_proxy" or "$no_proxy"
         environment variables.

         If the server requires authentication, user name and password may be  specified  in  the
         URL,     for     example     "https://user:password@my.server.org/image.raw.bz2",     or
         "ssh://user:password@host:path/to/image.raw".

         IMAGE may be compressed,  in  which  case  bmaptool  decompresses  it  on-the-fly.   The
         compression  type  is  detected  by  the file extension and the following extensions are
         supported:

             1. ".gz", ".gzip", ".tar.gz" and ".tgz" for files and tar archives  compressed  with
             "gzip" program
             2.  ".bz2",  "tar.bz2",  ".tbz2",  ".tbz",  and  ".tb2"  for  files and tar archives
             compressed with "bzip2" program
             3. ".xz", ".tar.xz", ".txz" for files and tar archives compressed with "xz" program
             4. ".lzo", "tar.lzo", ".tzo" for  files  and  tar  archives  compressed  with  "lzo"
             program
             4.  ".lz4",  "tar.lz4",  ".tlz4"  for  files  and tar archives compressed with "lz4"
             program

         IMAGE files with other extensions are assumed to be uncompressed.  Note,  bmaptool  uses
         "pbzip2"  and  "pigz"  programs for decompressing bzip2 and gzip archives faster, unless
         they are not available, in which case if falls-back to using "bzip2" and "gzip".

         If DEST is a block device node (e.g., "/dev/sdg"), bmaptool opens it in exclusive  mode.
         This  means  that  it will fail if any other process has IMAGE block device node opened.
         This also means that no other processes will  be  able  to  open  IMAGE  until  bmaptool
         finishes  the  copying.  Please,  see  semantics  of  the  "O_EXCL" flag of the "open()"
         syscall.

         The bmap file typically contains SHA-256 checksum for itself as well as SHA-256 checksum
         for  all  the  mapped data regions, which makes it possible to guarantee data integrity.
         bmaptool verifies the checksums and exits with an error in case of a mismatch.  Checksum
         verification  can  be  disabled using the "--no-verify" option. bmaptool does not verify
         that unampped areas contain only zeroes, because these areas are anyway dropped and  are
         not used for anything.

         The  bmap file may be signed with OpenPGP (gpg). The signature may be either detached (a
         separate file) or "built into" the bmap file (so called "clearsign" signature).

         The detached signature can be specified with the "--bmap-sig" option, otherwise bmaptool
         tries  to  automatically discover it by looking for a file with the same basename as the
         bmap file but with the ".asc" or ".sig" extension.  This is very  similar  to  the  bmap
         file  auto-discovery.  So  if  a  ".asc" or ".sig" file exists, bmaptool will verify the
         signature.

         The clearsign signature is part of the bmap file and bmaptool automatically detected and
         verifies it.

         If  the signature is bad, bmaptool exits with an error. Bmap file signature verification
         can be disabled using the "--no-sig-verify" option.

         OPTIONS
           -h, --help
             Print short help text about the "copy" command and exit.

           --bmap BMAP
             Use bmap file "BMAP" for copying. If this option is not specified, bmaptool tries to
             automatically discover the bmap file.

           --bmap-sig SIG
             Use  a  detached  OpenPGP signature file "SIG" for verifying the bmap file integrity
             and publisher. If this option is not  specified,  bmaptool  tries  to  automatically
             discover the signature file.

           --nobmap
             Disable automatic bmap file discovery and force flashing entire IMAGE without bmap.

           --no-verify
             Do  not  verify  data  checksums  when  copying (not recommended). The checksums are
             stored in the bmap file, and normally bmaptool  verifies  that  the  data  in  IMAGE
             matches the checksums.

           --no-sig-verify
             Do not verify the OpenPGP bmap file signature (not recommended).

           EXAMPLES
             bmaptool copy image.raw.bz2 /dev/sdg
               Copy  bz2-compressed  local  file  "image.raw.bz2" to block device "/dev/sdg". The
               image file is uncompressed on-the-fly. The bmap file is discovered  automatically.
               The OpenPGP signature is detected/discovered automatically too.

             bmaptool copy http://my-server.com/files/image.raw.bz2 $HOME/tmp/file
               Copy  bz2-compressed remote "image.raw.bz2" to regular file "$HOME/tmp/file".  The
               image file is uncompressed on-the-fly. The bmap file is discovered  automatically.
               The OpenPGP signature is detected/discovered automatically too.

             bmaptool copy --bmap image.bmap --bmap-sig image.bmap.asc image.raw /dev/sdg
               Copy  non-compressed  local file "image.raw" to block device "/dev/sdg" using bmap
               file "image.bmap". Verify  the  bmap  file  signature  using  a  detached  OpenPGP
               signature from "imag.bmap.asc".

   create [options] IMAGE
       Generate  bmap  for a regular file IMAGE. Internally, this command uses the Linux "FIEMAP"
       ioctl to find out which IMAGE blocks are mapped. However, if "FIEMAP"  is  not  supported,
       the  "SEEK_HOLE"  feature  of  the  "lseek"  system  call is used instead. By default, the
       resulting bmap file is printed to stdout, unless the "--output" option is used.

       The IMAGE file is always synchronized before  the  block  map  is  generated.  And  it  is
       important  to  make  sure  that the IMAGE file is not modified when the bmap file is being
       generated, and after the bmap file has been generated. Otherwise  the  bmap  file  becomes
       invalid and checksum verification will fail.

       The image file can further be signed using OpenPGP.

         OPTIONS
           -h, --help
             Print short help text about the "create" command and exit.

           -o, --output OUTPUT
             Save  the  generated  bmap  in  the  OUTPUT  file (by default the bmap is printed to
             stdout).

           --no-checksum
             Generate a bmap file without SHA1 checksums (not recommended).

         EXAMPLES
           bmaptool create image.raw
             Generate bmap for the "image.raw" file and print it to stdout.

           bmaptool create -o image.bmap image.raw
             Generate bmap for the "image.raw" file and save it in "image.bmap".

AUTHOR

       Artem Bityutskiy <artem.bityutskiy@linux.intel.com>.

REPORTING BUGS

       Please, report bugs to Artem Bityutskiy <artem.bityutskiy@linux.intel.com> or to the bmap-
       tools mailing list <bmap-tools@lists.infradead.org>.