commands.xml

<?xml version="1.0" encoding="utf-8"?>
<!--
This file describes the various fb-adb sub-commands
and the options they take.  From this file, we generate
the fb-adb man page, in-program usage, option-processing
code, and bash completion file.
-->
<usage program="fb-adb" summary="Improved Android Debug Bridge">
  <?ifndef HTML?>
  <section name="Synopsis">
    <!-- Automatically generated -->
    <synopsis/>
  </section>
  <?endif?>

  <section name="Description">
    <b>fb-adb</b> wraps <b>adb</b> to provide enhanced shell, command
    execution, file transfer, system diagnostic, and
    other functionality.
    <vspace/>
    <b>fb-adb shell</b> (which can also be spelled <b>fb-adb sh</b>
    and <b>fb-adb shellx</b>) runs <i>command</i> and its arguments
    through the device shell (which is usually <b>mksh</b>(1)) with
    all arguments shell-quoted.  (<i>command</i> itself is unquoted,
    so it may contain shell constructs, e.g., globs.)  <b>fb-adb
    shell</b> without arguments starts an interactive shell, making it
    slightly more efficient, especially when connecting to
    CPU-constrained devices.
    <vspace/>
    <b>fb-adb rcmd</b> is similar, except that it runs <i>command</i>
    directly without invoking the shell and does not have a
    zero-argument form that starts an interactive shell.
    <vspace/>
    <b>fb-adb rdex</b> does everything necessary to execute a jar file
    already on device as its own program.
    <vspace/>
    <b>fb-adb help</b> displays this documentation.
    <vspace/>
    See below for other useful commands, such as <b>fb-adb finfo</b>
    for describing the filesystem in JSON, <b>fb-adb logcat-json</b>
    for machine-readable logcat, <b>fb-adb ps-json</b>, and <b>fb-adb
    bash-completion</b>.
    <vspace/>
    <b>adb</b> must be on PATH.
  </section>

  <section name="Advantages over ADB">
    <b>fb-adb</b>
    <ul>
      <li>provides bash tab completion functions for everything</li>
      <li>is very fast: an AF_UNIX daemon allows us to start at interactive speeds</li>
      <li>is binary clean (no LF -> CRLF mangling),</li>
      <li>supports a variety of useful utility commands for running native and Java code on device</li>
      <li>transmits and updates terminal window size via
      SIGWINCH,</li>
      <li>distinguishes standard output and standard error,</li>
      <li>properly muxes streams, each with independent flow
      control,</li>
      <li>allows for ssh-like pty allocation control,</li>
      <li>propagates program exit status instead of always exiting
      with status 0,</li>
      <li>properly escapes program arguments,</li>
      <li>kills remote program on local exit,</li>
      <li>provides a generic facility to elevate to root without
      re-escaping command line arguments,</li>
      <li>transparently supports alternate, faster transports for
      shell connections,</li>
      <li>supports sending environment variables to the child using
      dedicated command-line parameters and no shell munging, and</li>
      <li>provides dedicated commands for filesystem access, logcat
      writing, etc. that are intended for use with scripts,</li>
      <li>is rapidly updated.</li>
    </ul>
  </section>

  <optgroup name="adb"
            forward="no"
            export-emit-args="yes"
            completion-relevant="yes">
    <option short="d" long="device">
      Connect to a device.  Identical to <b>adb</b>'s
      <b>-d</b> option.
    </option>
    <option short="e" long="emulator">
      Connect to an emulator.  Identical to <b>adb</b>'s
      <b>-e</b> option.
    </option>
    <option short="s" long="serial" arg="serial" >
      Connect to a specific device.  Identical to <b>adb</b>'s
      <b>-s</b> option.
    </option>
    <option short="H" long="hostname" arg="hostname" type="hostname">
      Specifies the hostname of the <b>adb</b> server to which to
      connect.  Identical to <b>adb</b>'s <b>-H</b> option.
    </option>
    <!-- Can't use service-name completion for port: ADB demands a
         positive number less than 2^16. -->
    <option short="P" long="port" arg="port">
      Specifies the port of the <b>adb</b> server to which to connect.
      Identical to <b>adb</b>'s <b>-P</b> option.
    </option>
  </optgroup>
  <optgroup name="transport" forward="no">
    <option short="X"
            long="transport"
            arg="transport"
            type="enum:shell;unix;tcp:*">
      Connect over the given transport.  The default is <b>shell</b>.
      <vspace/>
      <b>shell</b> means to run the <b>fb-adb</b> protocol over an
      "adb shell" connection.  This method is the most reliable.
      <vspace/>
      <b>unix</b> means to run the <b>fb-adb</b> protocol over an
      AF_UNIX socket connection forwarded over ADB.  This method may
      transfer data faster than the <b>shell</b> transport, but it is
      experimental may take slightly longer to set up.
      <vspace/>
      <b>tcp:HOST,PORT</b> means to use a TCP socket to connect from
      the device to the host.  fb-adb automatically manages making the
      connection, but it cannot automatically figure out on what
      network address the device can reach the host.  You must tell it
      what address to bind to: HOST and PORT.  HOST and PORT are any
      strings accepted as the node and service arguments,
      respectively, to getaddr(3), and can be names or numbers.
      <vspace/>
      Examples: <tt>tcp:10.2.5.1,12345</tt> and
      <tt>tcp:myhost.example,gopher</tt>
      <vspace/>
      This transport is typically much faster than the others: it
      bypasses <b>adb</b> completely.
      <vspace/>
      Note that traffic to devices is unencrypted.
      <?ifdef HAVE_LOCAL_STUB?>
      <vspace/>
      The <b>local</b> transport is a special mode that makes
      <b>fb-adb</b> connect to the device on which it's running
      instead of any connected Android device. This mode is primarily
      useful for debugging <b>fb-adb</b> itself.
      <?endif?>
    </option>
    <option long="avoid-daemon">
      <b>fb-adb</b> normally automatically starts a daemon on device
      to improve connection setup performance.  This option prevents
      <b>fb-adb</b> from starting a daemon or attempting to use one
      already started.
    </option>
  </optgroup>
  <optgroup name="user" forward="no" completion-relevant="yes">
    <option short="r" long="root">
      Attempt to become root.
    </option>
    <!-- XXX: implement username argtype -->
    <option short="u" long="user" arg="user">
      Attempt to become <i>user</i>.  <i>user</i> is an identifier
      that <b>run-as</b> on the device understands, e.g.,
      <tt>com.facebook.wakizashi</tt>.
      <vspace/>
      Note that some devices have broken <b>run-as</b>
      implementations: on these devices, <b>run-as</b> will not
      recognize a package never even though <tt>fb-adb rcmd am list
      packages</tt> indicates that the package is on the device.
    </option>
  </optgroup>
  <optgroup name="cwd" forward="no">
    <option short="C"
            long="chdir"
            arg="dir"
            type="device-path">
      Change to <i>dir</i> on device.
    </option>
  </optgroup>
  <optgroup name="shex" forward="no" human="Shell Control">
    <option short="D" long="no-ctty">
      Do not give the remote child a controlling terminal.  Normally,
      <b>fb-adb</b> connects a remote child to a controlling terminal
      so that when the a <b>fb-adb</b> disconnects, the child receives
      a SIGHUP.  With this option set, the child instead sees its
      standard streams closed, but is not sent any signal.
    </option>
    <option short="t" long="force-tty" accumulate="termops">
      Normally, if a <i>command</i> is supplied, <b>fb-adb</b> gives
      the remote child pipes for its standard streams.  This option
      instructs <b>fb-adb</b> to instead use a pseudoterminal for each
      standard stream connected to a terminal on the client.
      If repeated, <b>-t</b> makes <b>fb-adb</b> give the child a
      pseudoterminal even for streams for which the <b>fb-adb</b>
      client does not have a terminal.
    </option>
    <option short="T" long="disable-tty" accumulate="termops">
      Never give the child ttys for standard input, standard output,
      or standard error.  Use pipes instead, even if <b>fb-adb</b>
      itself is connected to a tty.
    </option>
    <option short="E" long="exename" arg="exename">
      Execute <i>exename</i> as the remote child program instead of
      <i>command</i>.  <i>command</i> is argv[0] in any case.
      If starting an interactive shell, use <i>command</i> instead of
      the default shell executable.
    </option>
    <option short="Y" long="setenv" arg="envvar" accumulate="uenvops">
      Set <i>envvar</i> in the environment of the child.
      <i>envvar</i> must a string of the form "NAME=VALUE".  If the
      <b>-Y</b> option is given multiple times, we set multiple
      environment variables.
      <vspace/>
      <b>fb-adb</b> applies the <b>-Y</b>, <b>-F</b>, and <b>-K</b>
      environment operations in the order they appear on the
      command line.
    </option>
    <option short="F" long="clearenv" accumulate="uenvops">
      Clear all environment variables set so far, both ones
      inherited from the environment and ones previously specified with
      <b>--setenv</b>.
    </option>
    <option short="K" long="unsetenv" arg="envvar" accumulate="uenvops">
      Unset the environment variable <i>envvar</i>.
    </option>
  </optgroup>
  <optgroup name="xfer" human="File Transfer">
    <option long="write-mode" arg="write-mode" type="enum:atomic;inplace">
      Control how we write files on whatever machine receives them.
      <vspace/>
      In <b>atomic</b> mode, we write to a uniquely-named temporary
      file in the same directory as the target file, then rename the
      temporary file on top of the destination file after fully
      writing it.  This way, no program can observe an
      incompletely-written file under the destination filename.
      <vspace/>
      In <b>inplace</b> mode, we write directly to the target file,
      first truncating it.
      <vspace/>
      By default, we use <b>atomic</b> mode, except that we use
      <b>inplace</b> when the destination file has a link count
      greater than one (in which case atomic mode would break the hard
      link), when the destination is not a regular file, or when we do
      not have write access to the destination file's parent
      directory.  The <i>write-mode</i> option overrides
      this heuristic.
    </option>
    <option long="sync">
      Use fsync(2) to make sure written files reach stable storage
      before indicating success.
    </option>
    <option short="p" long="preserve">
      Preserve modification times and UGO permission bits.  (We don't
      try to preserve ownership: UIDs aren't the same across
      different systems.)
    </option>
    <option long="mode" arg="octal-ugo">
      Set an explicit permissions on the written file, overriding both
      the default umask and permissions from the
      <b>--preserve</b> option.
    </option>
  </optgroup>
  <command names="help">
    Display help.
    <argument name="for-command" optional="yes" type="fbadb-command">
      Command for which to display help.  If omitted, display help for
      all commands.
    </argument>
  </command>
  <?ifdef FBADB_MAIN?>
  <command names="bash-completion">
    Write bash completion functions for <b>fb-adb</b> to stdout.
    Use like this: <pre>eval "$(fb-adb bash-completion)"</pre>
  </command>
  <?endif?>
  <command names="logwrite,logw">
    Write to logcat on device.
    <argument name="message-parts" repeat="yes">
      The log message to write.  All message arguments are joined with
      a single space character between them.  The combined message is
      then logged.
    </argument>
    <optgroup name="logwrite">
      <option short="t" long="tag" arg="tag">
        Log mesage with the given tag instead of the default,
        "fb-adb-logwrite".
      </option>
      <option short="x"
              long="priority"
              arg="priority"
              type="enum:verbose;debug;informational;warning;error;fatal"
              >
        Log message with the given priority instead of the default,
        <tt>informational</tt>.
      </option>
    </optgroup>
    <?ifdef FBADB_MAIN?>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
    <optgroup-reference name="user"/>
    <?endif?>
  </command>
  <command names="ctar">
    The <b>fb-adb ctar</b> command produces a tar file from the given
    <i>path</i> arguments.
    <argument name="paths" type="device-path" optional="yes" repeat="yes">
      Names of a file or directories to include in the tar archive.
    </argument>
    <optgroup name="ctar">
      <option short="f"
              long="ignore-errors">
        The <b>--ignore-errors</b> option tells <b>fb-adb ctar</b> to
        silently omit from the archive files that could not be opened.
      </option>
      <option long="exclude" arg="glob-pattern" accumulate="excludes">
        Exclude from the archive any file whose basename matches
        <i>glob-pattern</i>, a shell-style glob pattern.
        Multiple <b>--exclude</b>, <b>--exclude-regex</b>,
        <b>--include</b>, and <b>--include-regex</b> options may
        be given.
      </option>
      <option long="exclude-regex" arg="eregex" accumulate="excludes">
        Exclude from the archive any file whose full path (as
        constructed from an entry in <i>paths</i> matches
        <i>exclude-regex</i>, a POSIX-style regular expression.
        Multiple <b>--exclude</b>, <b>--exclude-regex</b>,
        <b>--include</b>, and <b>--include-regex</b> options may
        be given.
      </option>
      <option long="include" arg="glob-pattern" accumulate="excludes">
        Include in the archive only files whose basenames matches
        <i>glob-pattern</i>, a shell-style glob pattern.
        Multiple <b>--exclude</b>, <b>--exclude-regex</b>,
        <b>--include</b>, and <b>--include-regex</b> options may
        be given.
      </option>
      <option long="include-regex" arg="eregex" accumulate="excludes">
        Include in the archive only files whose full path (as
        constructed from an entry in <i>paths</i>) matches
        <i>exclude-regex</i>, a POSIX-style regular expression.
        Multiple <b>--exclude</b>, <b>--exclude-regex</b>,
        <b>--include</b>, and <b>--include-regex</b> options may
        be given.
      </option>
    </optgroup>
    <?ifdef FBADB_MAIN?>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
    <optgroup-reference name="user"/>
    <optgroup-reference name="cwd"/>
    <?endif?>
  </command>
  <command names="readlink">
    Read the target of a symbolic link on device.  This command is
    useful when a device lacks the readlink(1) command.
    <b>readlink</b> prints the given link's target to standard output
    (with no trailing newline) or fails.
    <argument name="link" type="device-path">
      The name of the symbolic link to read.
    </argument>
    <?ifdef FBADB_MAIN?>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
    <optgroup-reference name="user"/>
    <optgroup-reference name="cwd"/>
    <?endif?>
  </command>
  <command names="rdex">
    Run a dex file using the remote machine's VM.
    Automatically compiles the dex file to an odex or oat file.
    <argument name="dexfile" type="device-path">
      Name of the dex-containing jar file file to run.
    </argument>
    <argument name="classname">
      Name of the class file to run.
    </argument>
    <argument name="args" repeat="yes" optional="yes" type="device-path">
      Arguments to send to <i>dexfile</i>.
    </argument>
    <optgroup name="rdex">
      <option long="no-compile">
        If set, do not attempt to compile the given dex file.
        Execute it as-is.
      </option>
    </optgroup>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
    <optgroup-reference name="user"/>
    <optgroup-reference name="cwd"/>
    <optgroup-reference name="shex"/>
  </command>
  <command names="xdex" env="main">
    Run a local dex.jar file on the remote machine, automatically
    taking care of copying the dex file (if needed) to the remote
    machine, compiling it there to an odex or oat file, and so on.
    xdex is to rdex as xcmd is to rcmd.  xdex's interface is
    considerably simpler, however, since .dex.jar files are
    architecture-neutral.
    <argument name="program" type="host-path">
      Name of the program to run.  If it contains a slash, we try to
      run that file exactly and no other.  Otherwise, look up the dex
      file to run on the dex path, which is the value of the
      <b>--path</b> argument, or if that is unset, the
      <b>FB_ADB_XDEX_PATH</b> environment variable, or if that is
      unset, the current directory.
      <vspace/>
      To find the dex file to run on device, we look in each path
      location for 1) a file called exactly <i>program</i>, and 2) a
      file called <i>program</i>.dex.jar.  If we find a matching file,
      we use it as if it had been specified explicitly, with slashes.
      Otherwise, we move on to the next path entry.  If we consult all
      path entries and don't find the file, we fail.
    </argument>
    <argument name="classname">
      Name of the class inside the dex file to run.  The class must
      provide a conventional Java <tt>public static void main(String[]
      args)</tt> method.
    </argument>
    <argument name="args" repeat="yes" optional="yes" type="device-path">
      Arguments to send to the <i>program</i>.
    </argument>
    <optgroup name="xdex">
      <option long="path">
        Colon-separated list of paths to search for xdex binaries; if
        supplied, overrides the value of the <b>FB_ADB_XDEX_PATH</b>
        environment variable.
      </option>
    </optgroup>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
    <optgroup-reference name="user"/>
    <optgroup-reference name="cwd"/>
    <optgroup-reference name="shex"/>
  </command>
  <command names="xdex-stub" internal="true" env="stub">
    Internal command for implementing the device side of xdex processing.
    <argument name="name">
      Base filename of dex jar file
    </argument>
  </command>
  <command names="agent" env="main">
    Directly run the built-in device-side Java agent, which has its
    own command line syntax.  Run <tt>fb-adb agent -- -h</tt>
    for details.
    <argument name="args" repeat="yes" optional="yes" type="device-path">
      Arguments to send to the agent.
    </argument>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
    <optgroup-reference name="user"/>
  </command>
  <command names="ps-json">
    Output the machine's process list in JSON.
    <?ifdef FBADB_MAIN?>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
    <?endif?>
  </command>
  <command names="getprop">
    Read zero, more, or all system properties from a device and
    describe them in JSON.  Standard output is a JSON object with one
    field per property, the property name being the string value of
    the property.  If any requested property is not found, emit null
    in the JSON output and exit with status code 4.  (Ordinarily, we
    exit with status code 1 on error.)
    <argument name="properties"
              type="device-property"
              optional="yes"
              repeat="yes">
      Names of properties to read.  If omitted, print all properties.
    </argument>
    <optgroup name="getprop">
      <option short="f" long="format" arg="format-string">
        Provide a format string for printing property values.  In this
        format string, <b>fb-adb getprop</b> substitutes <tt>%n</tt>
        with the property name and substitutes <tt>%v</tt> with the
        property value.  A newline is printed after each property
        unless <b>-0</b> is supplied; in that case, a NUL separates
        each property.  To output a literal <tt>%</tt>, write
        <tt>%%</tt>.  Only properties that are found are output this way.
      </option>
      <option short="F" long="format-not-found" arg="format-string">
        Provide a format string for printing property values not
        found.  In this format string, <b>fb-adb getprop</b>
        substitutes <tt>%n</tt> with the name of the property not
        found.  A newline is printed after each property unless
        <b>-0</b> is supplied; in that case, a NUL separates each
        property.  To output a literal <tt>%</tt>, write <tt>%%</tt>.
      </option>
      <option short="0" long="null">
        When using <b>-f</b> for formatting instead of emitting JSON,
        separate properties with a NUL byte instead of with a newline.
      </option>
    </optgroup>
    <?ifdef FBADB_MAIN?>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
    <optgroup-reference name="user"/>
    <?endif?>
  </command>
  <?ifdef FBADB_MAIN?>
  <command names="logcat-json">
    Write logcat records as JSON, one JSON-formatted log record per
    line.  We always use line buffering; combining this mode with
    jq(1) is recommended for readability.
    <optgroup name="logcat-json">
      <option long="time-format" arg="strftime-format-string">
        Specify how to format time in log records.  Defaults to
        RFC822 time.
      </option>
      <option long="gmt">
        Print time in GMT, not local time.
      </option>
    </optgroup>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
    <optgroup-reference name="user"/>
  </command>
  <?endif?>
  <command names="finfo-json">
    Print information in JSON format about paths on device.
    The output is a JSON array with one entry for each of the
    given paths.
    <!-- XXX: DOCUMENT ME BETTER! -->
    <argument name="paths"
              repeat="yes"
              optional="yes"
              type="device-path">
      The paths to query on device.
    </argument>
    <optgroup name="finfo">
      <option short="i" long="info" arg="info">
        Comma-separated list of pieces of information to retrieve from
        each of the paths given.
      </option>
    </optgroup>
    <?ifdef FBADB_MAIN?>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
    <optgroup-reference name="user"/>
    <optgroup-reference name="cwd"/>
    <?endif?>
  </command>
  <command names="fcat">
    Write the contents of zero or more device files to standard output.
    <argument name="files" type="device-path" repeat="yes" optional="yes">
      Names of files to write.
    </argument>
    <?ifdef FBADB_MAIN?>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
    <optgroup-reference name="user"/>
    <optgroup-reference name="cwd"/>
    <?endif?>
  </command>
  <command names="xfer-stub" internal="true">
    Internal command for implementing the device side of file transfer.
    <argument name="mode" type="enum:send;receive">
      <tt>send</tt> or <tt>recv</tt> indicating that the stub
      should receive or send, respectively, the file data.
    </argument>
    <argument name="filename">
      Name of the file to open.
    </argument>
    <argument name="desired-basename" optional="yes">
      Basename of desired file in case <i>filename</i> is a directory.
    </argument>
    <optgroup-reference name="xfer" />
  </command>
  <?ifdef FBADB_MAIN?>
  <command names="fget">
    Retrieve a file from device.  Note that there is no recursive
    option: to retrieve multiple files, use the <b>fb-adb ctar</b>
    command to stream a tar file containing the files you want; you
    can pipe the output of <b>fb-adb ctar</b> to your favorite
    <b>tar</b> program for unpacking.
    <argument name="remote" type="device-path">
      Name of the file on device.
    </argument>
    <argument name="local"
              type="host-path"
              optional="yes">
      Name of the file to write on the host.  If <i>local</i> is a
      directory, write to the file <tt>basename(<i>remote</i>)</tt> in
      this directory.  If <i>local</i> is omitted, it defaults to the
      current directory.
    </argument>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
    <optgroup-reference name="user"/>
    <optgroup-reference name="cwd"/>
    <optgroup-reference name="xfer" />
  </command>
  <?endif?>
  <?ifdef FBADB_MAIN?>
  <command names="fput">
    Store a file on device.
    <argument name="local" type="host-path">
      Name of the file on host.  If <tt>-</tt> (a single dash)
      read from standard input.
    </argument>
    <argument name="remote"
              type="device-path"
              optional="yes">
      Name of the file to write on the device.  If <i>remote</i> is a
      directory, write to the file <tt>basename(<i>local</i>)</tt> in
      this directory.  If <i>remote</i> is omitted, it defaults to
      <tt>basename(<i>local</i>)</tt> in the default directory for
      <b>fb-adb rcmd</b> (except if <i>local</i> is <tt>-</tt>, in
      which case the command fails as we have no basename.)
    </argument>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
    <optgroup-reference name="user"/>
    <optgroup-reference name="cwd"/>
    <optgroup-reference name="xfer" />
  </command>
  <?endif?>
  <command names="ping" env="main">
    Measure round trip time to device.
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
  </command>
  <command names="_echo" internal="yes" env="stub">
    Internal command that echoes the input.
  </command>
  <?ifdef FBADB_MAIN?>
  <command names="shell,shellx,sh">
    Run a command on device.  If <i>command</i> is not supplied, run
    an interactive shell.  Otherwise, run <i>command</i> on device
    with the given arguments.  <i>command</i> is interpreted as a
    shell command and is not quoted; the arguments are each quoted.
    This quoting system means that glob patterns in arguments will not
    be expanded, while glob patterns in <i>command</i> will be.
    <argument name="command" type="device-command" optional="yes">
      Name of the command to run: can be a program or shell builtin.
    </argument>
    <argument name="args" repeat="yes" optional="yes" type="device-path">
      Arguments to send to the <i>command</i>.
    </argument>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
    <optgroup-reference name="user"/>
    <optgroup-reference name="cwd"/>
    <optgroup-reference name="shex"/>
  </command>
  <command names="rcmd">
    Run a command on device.  Unlike <b>fb-adb shell</b>, this command
    does not invoke the shell.  It instead runs
    <b>command</b> directly.
    <argument name="command" type="device-exe">
      Program to run on device.  This argument will become
      <tt>argv[0]</tt> and is also the name of the executable to run
      if one is not specified with <b>--exename</b>.
    </argument>
    <argument name="args" repeat="yes" optional="yes" type="device-path">
      Arguments to send to the <i>command</i>.
    </argument>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
    <optgroup-reference name="user"/>
    <optgroup-reference name="cwd"/>
    <optgroup-reference name="shex"/>
  </command>
  <command names="rcmd-self" internal="yes" export-parse-args="yes">
    Like <b>fb-adb rcmd</b>, except that the program to run is
    hard-wired to be the <b>fb-adb</b> stub itself.  This special case
    is necessary to properly propagate argv0.
    <argument name="args" repeat="yes" optional="yes" type="device-path">
      Arguments to send to the inferior <b>fb-adb</b>.  The first
      argument is the command to run.
    </argument>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
    <optgroup-reference name="user"/>
    <optgroup-reference name="cwd"/>
    <optgroup-reference name="shex"/>
  </command>
  <command names="xcmd">
    Run a program on device, transferring it to the device first
    if necessary.
    <vspace/>
    <b>fb-adb xcmd</b> makes it easy to run arbitrary programs on
    Android devices without having to worry about getting them to
    devices first, making sure that specific builds are compatible
    with specific devices, and other headaches.  <b>fb-adb xcmd</b>
    works by first identifying <i>candidate</i> binaries matching the
    <i>command</i> argument, making sure that binary exists on the
    system, then running it.
    <vspace/>
    <b>fb-adb xcmd</b> finds candidates first by considering all the
    explicitly passed <b>--candidate</b> options, then searching for
    <b>program</b> in all the directories given in
    <b>FB_ADB_XCMD_PATH</b>.  The first file matching the architecture
    of the device is the one we use.
    <argument name="program" type="host-path">
      Name of the program to run; it must not contain a slash.
    </argument>
    <argument name="args" repeat="yes" optional="yes" type="device-path">
      Arguments to send to the <i>program</i>.
    </argument>
    <optgroup name="xcmd">
      <option long="candidate" arg="executable" accumulate="candidates">
        Candidate to consider for execution.  <i>executable</i> is a
        filename; it is considered as an xcmd execution candidate
        before entries found in the candidate path.
        <b>--candidate</b> can be given multiple times; each supplied
        <i>executable</i> is considered in order.
      </option>
      <option long="candidate-path" arg="path">
        Colon-separated list of paths to search for xcmd binaries; if
        supplied, overrides the value of the <b>FB_ADB_XCMD_PATH</b>
        environment variable.
      </option>
    </optgroup>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
    <optgroup-reference name="user"/>
    <optgroup-reference name="cwd"/>
    <optgroup-reference name="shex"/>
  </command>
  <?endif?>
  <command names="stub-package-hack" internal="yes" env="stub">
    This internal command attempts to use <tt>FbAdbService</tt> to
    start a daemon in a package without using run-as.
    <argument name="package" />
  </command>
  <command names="start-daemon">
    Start an fb-adb daemon on the device.  <b>fb-adb</b> will connect
    to this daemon the next time it needs to run a command.
    <?ifdef FBADB_MAIN?>
    Each user has a daemon, so the <b>--user</b> option controls which
    daemon to start.
    <?endif?>
    <optgroup name="start-daemon">
      <option long="replace">
        Kill any existing <b>fb-adb</b> daemon for this user before
        starting a new daemon.  Without this option, we reuse an
        already-started daemon as long as its version matches our own.
      </option>
    </optgroup>
    <?ifdef FBADB_MAIN?>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
    <optgroup-reference name="user"/>
    <?endif?>
  </command>
  <command names="stop-daemon">
    Stop the most recently started <b>fb-adb</b> daemon.
    <?ifdef FBADB_MAIN?>
    Each user has a daemon, so the <b>--user</b> option controls which
    daemon to kill.
    <?endif?>
    <?ifdef FBADB_MAIN?>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
    <optgroup-reference name="user"/>
    <?endif?>
  </command>
  <command names="stub" internal="yes" env="stub">
    Internal command that the fb-adb host program invokes on device to
    implement remote commands.  Start speaking the <b>fb-adb</b> protocol
    on standard input and output.
    <optgroup name="stub">
      <option short="l" long="listen">
        Instead of speaking the <b>fb-adb</b> protocol on standard
        input and output, listen on a randomly-named abstract AF_UNIX
        socket, print FB_ADB_STUB_DAEMONIZED_LINE on standard output,
        and begin accepting connections.  We use this mode of
        operation to work around bugs in Android <b>run-as</b>.
      </option>
      <option short="d" long="daemonize">
        Put this program into the background before beginning to
        listen for connections.  Useful only with <b>--listen</b>.
      </option>
      <option short="r" long="replace">
        Kill any existing <b>fb-adb</b> daemon for this user before
        starting a new one.
      </option>
    </optgroup>
  </command>
  <command names="jdwp" env="main">
    Set up a JDWP proxy that connects to a remote process
    <optgroup name="jdwp">
      <option short="p" long="jdwp-listen-port" arg="port" type="string">
        TCP port on which to listen (on the local machine, not the remote)
        for a JDWP connection.
      </option>
      <option short="q" long="quiet">
        Do not emit non-error messages about the debugging session on
        standard error.
      </option>
      <option long="suspend">
        Suspend the VM upon connection.
      </option>
      <option short="m" long="mode" arg="mode" type="enum:auto;rewrite;dumb">
        Control transformations we apply to the JDWP protocol. In
        <b>auto</b> mode, automatically select <b>rewrite</b> or
        <b>dumb</b> depending on the detected VM.  In <b>dumb</b>
        mode, proxy debugger traffic literally.  In <b>rewrite</b>
        mode, perform protocol transformations that make it possible
        to debug large applications under ART.
      </option>
    </optgroup>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
    <argument name="to-what">
      Process to which to establish a JDWP debugging connection; if
      all digits, interpreted as a PID.  If a name, match as a
      process name.
    </argument>
  </command>
  <command names="pidof">
    Print the PID of the process with name <b>name</b>.  Fail if there
    is no process with that name or if multiple processes match.
    <optgroup name="pidof">
      <option short="0" long="zero">
        Do not terminate output with trailing newline; if multiple
        outputs, separate with NUL, not whitespace.
      </option>
    </optgroup>
    <argument name="name">
      Name of the process to look up.
    </argument>
    <optgroup-reference name="adb"/>
    <optgroup-reference name="transport" />
  </command>
  <section name="Environment Variables">
    <dl>
      <?ifdef FBADB_MAIN?>
      <dt>FB_ADB_XCMD_PATH</dt>
      <dd>Colon-separated list of directories in which to search for
      xcmd commands; see the discussion of <b>fb-adb xcmd</b>
      above.</dd>
      <?endif?>
      <?ifdef FBADB_MAIN?>
      <dt>FB_ADB_XDEX_PATH</dt>
      <dd>Like <b>FB_ADB_XCMD_PATH</b>, but for <b>.dex</b> or
      <b>.dex.jar</b> files instead of native binaries.</dd>
      <?endif?>
      <dt>ADB_SHELL_OLD_BEHAVIOR</dt>
      <dd>When set, <b>fb-adb</b> does not override any <b>adb</b>
      commands, exposing only new names for new commands.  Using this
      option, <b>fb-adb</b> can replace <b>adb</b> (perhaps on PATH)
      with no compatibility risk.
      </dd>
      <dt>FB_ADB_DEBUG</dt>
      <dd>This variable controls how <b>fb-adb</b> writes debug
      messages.  If it is "1", <b>fb-adb</b> writes debug messages to
      standard error.  If it is a string that begins with ">",
      <b>fb-adb</b> writes debug messages to the file whose names
      begins after the ">" (like a shell redirection).  If it is a
      string that begins with ">>", <b>fb-adb</b> appends to that file
      instead of overwriting it.  This environment variable only has
      an effect when <b>fb-adb</b> is compiled with the
      --enable-checking option.
      </dd>
      <?ifdef FBADB_MAIN?>
      <dt>FB_ADB_REMOTE_DEBUG</dt>
      <dd>This option, set on the host system, becomes the value of
      <b>FB_ADB_DEBUG</b> on the target system.
      </dd>
      <dt>FB_ADB_REMOTE_WRAPPER</dt>
      <dd>This option, set on the host system, provides a program that
      wraps the execution of the stub on the remote system.
      This environment variable has an effect only when the program is
      configured with --enable-checking.  An example:
      <tt>FB_ADB_REMOTE_WRAPPER='strace -o/data/local/tmp/foo'</tt>
      </dd>
      <dt>FB_ADB_NO_COMPRESSION</dt>
      <dd>This option, set on the host system, tells <b>fb-adb</b> to
      avoid its usual LZ4 stream compression.  LZ4 is fast enough that
      there are no practical disadvantages to disabling it, so this
      option is primarily useful for debugging.
      </dd>
      <dt>FB_ADB_TRANSPORT</dt>
      <dd>
        This environment variable provides the default value of the
        <b>--transport</b> option.
      </dd>
      <?endif?>
      <dt>FB_ADB_COLOR</dt>
      <dd>
        <b>fb-adb</b> normally tries to print help messages in color
        when sending help text to a color-capable terminal or
        color-capable pager.  If <b>FB_ADB_COLOR</b> is set to 1,
        force color output.  If <b>FB_ADB_COLOR</b> is 0, never output
        color.  (We consider any value of <b>PAGER</b> equal to
        <tt>less</tt> or starting with <tt>less </tt> to be
        color-capable.)
      </dd>
      <dt>PAGER</dt>
      <dd>
        <b>fb-adb</b> normally tries to display help text in a pager
        given by the <b>PAGER</b> environment variable.
        If <b>PAGER</b> is the empty string or fails, skip the pager
        and emit help text directly.
      </dd>
    </dl>
  </section>
  <section name="Examples">
    <dl>
      <dt>Capture a screenshot from device and write it locally</dt>
      <dd>
        <pre>
          <![CDATA[
  fb-adb rcmd screencap -p > screenshot-$(timestamp).png
          ]]>
        </pre>
      </dd>
      <dt>Dump database.db of the com.example.foo app</dt>
      <dd>
        <pre>
          <![CDATA[
  fb-adb rcmd -u com.example.foo sqlite3 databases/database.db .d
          ]]>
        </pre>
      </dd>
      <dt>Open remote shell as the user com.example.foo</dt>
      <dd>
        <pre>
          <![CDATA[
  fb-adb shell -u com.example.foo
          ]]>
        </pre>
      </dd>
      <dt>Retrieve all PNG files in your application's data directory</dt>
      <dd>
        <pre>
          <![CDATA[
  # The default directory with --user is the data directory
  # pv provides a pretty progress indicator
  fb-adb ctar -u com.example.foo --include=*.png . | pv -W > pngs.tar
          ]]>
        </pre>
      </dd>

    </dl>
  </section>
  <section name="See Also">
    Run <b>adb help</b> to see <b>adb</b>'s own list of commands.  Argument
    passing works roughly like ssh(1)'s.
  </section>
</usage>