path: root/doc/gphoto2.xml

<?xml version='1.0' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<book>

  <bookinfo>
    <title>The gPhoto2 Manual</title>
    <authorgroup>
      <author>
        <firstname>The gPhoto2</firstname>
        <surname>Team</surname>
      </author>
      <editor>
        <firstname>Tim</firstname>
        <surname>Waugh</surname>
        <affiliation>
	  <address><email>twaugh@redhat.com</email></address>
	</affiliation>
      </editor>
      <editor>
        <firstname>Hans Ulrich</firstname>
        <surname>Niedermann</surname>
        <affiliation>
	  <address><email>gp@n-dimensional.de</email></address>
	</affiliation>
      </editor>
    </authorgroup>
  </bookinfo>

  <chapter>
    <title>Short guide to setting up and using 
      <xref linkend="gphoto2-cli"/> and <xref linkend="libgphoto2"/>
    </title>
    <section>
      <title>Overview</title>
      <para>
        gPhoto2 consists of two libraries
        (<xref linkend="libgphoto2"/> and
        <xref linkend="libgphoto2_port"/>) and
        a command line frontend (<xref linkend="gphoto2-cli"/>). 
        Other (GUI) frontends (like e.g. gtkam) are available as
        separate packages.
      </para>
      <para>
        In order to get access to the camera, your frontend process requires
        write permissions to the respective device special file, e.g. to
        <filename class="devicefile">/dev/ttyS3</filename> or 
        <filename class="devicefile">/proc/bus/usb/1/012</filename>. 
      </para>
      <para>
        For security reasons, we strongly recommend not to run any 
        <xref linkend="libgphoto2"/>
        frontend as root. So you have to set up the permissions of your camera
        device accordingly. This is described in chapter 2 - Setting up
        permissions. 
      </para>
      <para>
        Then you can run your frontend. For the command line 
        <xref linkend="libgphoto2"/> frontend 
        <xref linkend="gphoto2-cli"/>,
        this is described in the <xref linkend="gphoto2-cli"/> man
        page.
      </para>    
    </section>

    <section>
      <title>Setting up permissions for serial (RS232) ports</title>
      <note>
        I don't have any experience with serial ports for user
        processes. So take this section with a grain of salt.
      </note>
      <para>
        If you have a serial port reserved for the camera, you may just chown
        the device file to the user you want to run gphoto2 as.
      </para>    
    </section>

    <section>
      <title>Setting up permissions for USB ports</title>
      <para>
        As USB allows hotplugging of devices, there is a mechanism that
        dynamically creates the device files for the devices currently
        connected and switched on.
      </para>
      <para>
        The operating system has to determine which users may access a device
        dynamically. As the operating system cannot determine this by itself,
        there have to be some helper applications.
      </para>
      <para>
        The configuration of these helper applications is explained in the
        following section.
      </para>

      <!-- ================================================== -->
      <section>
        <title>USB ports on Linux</title>
        <para>
          As gphoto2 provides a user space driver, in order to have gphoto2
          access your camera, you have to disable all kernel drivers which want
          to handle the camera themselves (e.g. the Linux dc2xx driver).
        </para>
        <para>
          On Linux systems, you have basically two options to allow user access
          to USB devices:
        </para>
        <orderedlist>
          <listitem id="usbdevfs">
            <simpara>
              allow a certain user/group or the world access to
              <emphasis>all</emphasis> USB devices
              by mounting 
              <filename class="directory">/proc/bus/usb</filename>
              with adequate user and/or group permissions (default
              is world-readable and root-only-writable, which is good)
            </simpara>
          </listitem>

          <listitem id="hotplug">
            <simpara>
              use hotplug (<ulink
                url="http://linux-hotplug.sourceforge.net/">http://linux-hotplug.sourceforge.net/</ulink>)
              and allow access only to the USB devices you want to be
              accessible (you need 
              <filename class="directory">/proc/bus/usb</filename>
              mounted here as well, but not mounted writable by
              anybody else than root) 
            </simpara>
          </listitem> 
        </orderedlist>

        <para>    
          Solution <xref linkend="hotplug"/> has a huge advantage over 
          <xref linkend="usbdevfs"/>: It doesn't allow the
          user/group to interfere with or eavesdrop on any other USB devices
          which might be attached, such as USB keyboards, fingerprint reader or
          similar. The following paragraphs thus describe setting up
          <xref linkend="hotplug"/>.
        </para>

        <para>
          On Linux systems, from the 2.4 kernel series on, the kernel supports
          hotplugging. You may have to compile a kernel with hotplug support if
          you're not already running one. You may have to install the hotplug
          package (<ulink url="http://linux-hotplug.sourceforge.net/">http://linux-hotplug.sourceforge.net/</ulink>) if you don't have it
          installed already.
        </para>

        <para>
          You can find out if your kernel has hotplug support by looking for the
          file <filename>/proc/sys/kernel/hotplug</filename>. 
          If it exists, you have a hotplug
          enabled kernel. If 
          <screen>
            <command>cat</command>
            <parameter>/proc/sys/kernel/hotplug</parameter>
          </screen> prints the path to
          your hotplug binary (usually 
          <command>/sbin/hotplug</command>) and this binary exists,
          you are ready to rock.
        </para>      

        <para>
          Also note that the following solution does
          <emphasis>not</emphasis> 
          provide absolute security and that you know the security
          implications of the respective <command>usbcam</command> 
          script you are going to use.
        </para>

        <orderedlist>
          <listitem>
            <formalpara>
            Load your USB driver and mount the USB device filesystem,
            i.e. e.g.
            <screen>
              <prompt># </prompt><command>modprobe</command> <parameter>usb-uhci</parameter>
              <prompt># </prompt><command>modprobe</command> <parameter>usb-ohci</parameter>
              <prompt># </prompt><command>mount</command> 
              <parameter>-t usbdevfs</parameter>
              <parameter>/proc/bus/usb</parameter>
            </screen>
                Modern distributions like Redhat 7.2 handle this
                automatically.
            </formalpara>
          </listitem>
          <!-- ==================== -->
          <listitem>
            <formalpara>
                Add the output of <command>gphoto2</command> <parameter>--print-usb-usermap</parameter> to
                <filename>/etc/hotplug/usb.usermap</filename>
                This makes hotplug recognise all USB cameras which your version 
                of <xref linkend="libgphoto2"/> supports and makes
                <command>hotplug</command> run the
                <command>usbcam</command> script you choose in step
                <xref linkend="chooseusbcamscript"/>whenever one of these
                cameras is attached.
            </formalpara>
          </listitem>
          <!-- ==================== -->
          <listitem id="chooseusbcamscript">
            <para>
              Choose the right 
              /etc/hotplug/usb/usbcam 
              script for you.
              Example scripts are found in 
              <filename class="directory">packages/linux-hotplug</filename> 
              in the source tree and in 
              <filename class="directory">linux-hotplug/</filename>
              after installation and in the doc dir of the binary
              package. Choose one, adapt it for your needs, and copy
              it to <filename>/etc/hotplug/usb/usbcam</filename>. The
              directory 
              <filename class="directory">/etc/hotplug</filename>
              should already exists, whereas it may be that you have
              to create the directory 
              <filename class="directory">/etc/hotplug/usb</filename>.
            </para>
            <para>
              All three scripts shipped with gPhoto2 also have extensive
              commentary explaining their usage in more detail.
            </para>
            <variablelist>
              <varlistentry>
                <term><filename>usbcam.console</filename></term>
                <listitem>
                  <para>
                    The most simple solution is using usbcam.console. This
                    changes the permissions so that the user owning /dev/console can
                    access the camera. This works if you're logging in with
                    pam_console, i.e. e.g. using gdm on Redhat Linux.
                  </para>
                  <para>
                    You may want to check with "ls -l /dev/console" whether this
                    usbcam.console script will work for you: /dev/console must
                    belong to the user you want to run the gphoto2 frontend as.
                  </para>              
                </listitem>
              </varlistentry>
              <varlistentry>
                <term><filename>usbcam.user</filename></term>
                <listitem>
                  <simpara>
                    If you want only one user to have access to the camera, use
                    <filename>usbcam.user</filename> and change it
                    accordingly.
                  </simpara> 
                </listitem>
              </varlistentry>
              <varlistentry>
                <term><filename>usbcam.group</filename></term>
                <listitem>
                  <simpara>
                    If you want multiple users to have access to the camera, add all
                    of these users to one group - either a special
                    group 
                    <systemitem class="groupname">camera</systemitem>
                    or a generic group 
                    <systemitem class="groupname">users</systemitem>
                    will do - and use that group in 
                    <filename>usbcam.group</filename>.</simpara>
                </listitem>
              </varlistentry>  
            </variablelist>
          </listitem>
          <!-- ==================== -->
          <listitem>
            <simpara>
              Make your script file
              <filename>/etc/hotplug/usb/usbcam</filename>
              executable.
            </simpara>
          </listitem>
          <!-- ==================== -->
          <listitem>
            <para>
              Plug in the camera and switch it on. If you already did so, please
              unplug and/or switch off first. The kernel will now notice that
              your camera has been connected and, hopefully finding no kernel
              driver for the device, will ask hotplug to do something about it.
            </para>
            <para>
              Hotplug will then look into 
              <filename>/etc/hotplug/usb.usermap</filename> and find that
              the <command>usbcam</command> script is to be called for
              the newly attached device. Thus
              <command>/etc/hotplug/usb/usbcam</command> is executed,
              hopefully setting the device permissions correctly. 
            </para>
            <para>Your <filename>/var/log/messages</filename> syslog
              file will contain some messages to that effect.
            </para>
          </listitem>
          <listitem>
            Run <xref linkend="gphoto2-cli"/> or any other 
            <xref linkend="libgphoto2"/> frontend and enjoy :-)
          </listitem>
        </orderedlist>
      </section>
    </section>
    <section>
      <title>Specifying the port and camera you use</title>
      <para>
        libgphoto2 identifies a camera two values:
        <orderedlist numeration="loweralpha">
          <listitem>
            <simpara>the port it is connected to</simpara>
          </listitem>
          <listitem>
            <simpara>the name of the camera</simpara>
          </listitem>
        </orderedlist>
      </para>
      <para>
        How these may be specified is discussed in the following
        sections.
      </para>
      
      <section>
        <title>Serial ports</title>
        <para>
          Serial ports are named like 
          <systemitem class="resource">serial:/dev/ttyS2</systemitem>
          if you want to use the serial device
          <filename class="devicefile">/dev/ttyS2</filename>.
        </para>
      </section>

      <section>
        <title>USB ports</title>
        <para>
          As USB works with auto detection, you do not have to specify a device
          file. Therefore you just use the gphoto2 port 
          <systemitem class="resource">usb:</systemitem>.
        </para>
      </section>

      <section>
        <title>Name of the camera</title>
        <para>
          The model name of the camera does not have to be specified when using
          the <systemitem class="resource">usb:</systemitem> port. 
          Otherwise you can specify a camera model like 
          <systemitem class="resource">Canon PowerShot G2</systemitem>. 
          You will be better off choosing the model from
          the list of supported models rather than just trying to type
          your camera model. 
        </para>
      </section>
    </section>
  </chapter>

<reference>
  <title>The gPhoto2 Reference</title>

  <refentry id="gphoto2-cli">
    <refentryinfo>
      <author>
	<firstname>The gPhoto2</firstname><surname>Team</surname>
      </author>

      <editor>
	<firstname>Tim</firstname>
	<surname>Waugh</surname>
	<affiliation>
	  <address><email>twaugh@redhat.com</email></address>
	</affiliation>
      </editor>

      <date>February 2002</date>
    </refentryinfo>

    <refmeta>
      <refentrytitle>gphoto2</refentrytitle>
      <manvolnum>1</manvolnum>
    </refmeta>

    <refnamediv>
      <refname>gphoto2</refname>
      <refpurpose>command-line <systemitem class="library">gphoto2</systemitem> client</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <cmdsynopsis>
	<command>gphoto2</command>
	<arg choice="opt">--debug</arg>
	<group choice="opt">
	  <arg>-q</arg>
	  <arg>--quiet</arg>
	</group>
	<group choice="opt">
	  <arg>-v</arg>
	  <arg>--verbose</arg>
	</group>
	<group choice="opt">
	  <arg>-h</arg>
	  <arg>--help</arg>
	</group><sbr/>
	<arg choice="opt">--list-cameras</arg>
	<arg choice="opt">--usb-usermap-script <replaceable>NAME</replaceable></arg><sbr/>
	<arg choice="opt">--print-usb-usermap</arg>
	<arg choice="opt">--list-ports</arg>
	<arg choice="opt">--stdout</arg><sbr/>
	<arg choice="opt">--stdout-size</arg>
	<arg choice="opt">--auto-detect</arg>
	<arg choice="opt">--port <replaceable>PATH</replaceable></arg><sbr/>
	<arg choice="opt">--speed <replaceable>SPEED</replaceable></arg>
	<arg choice="opt">--camera <replaceable>MODEL</replaceable></arg>
	<arg choice="opt">--filename <replaceable>FILENAME</replaceable></arg><sbr/>
	<arg choice="opt">--usbid <replaceable>USBID</replaceable></arg>
	<group choice="opt">
	  <arg>-a</arg>
	  <arg>--abilities</arg>
	</group>
	<arg choice="opt">--folder <replaceable>FOLDER</replaceable></arg><sbr/>
	<group choice="opt">
	  <group>
	    <arg>-R</arg>
	    <arg>--recurse</arg>
	  </group>
	  <arg choice="opt">--norecurse</arg>
	</group>
	<group choice="opt">
	  <arg>-l</arg>
	  <arg>--list-folders</arg>
	</group><sbr/>
	<group choice="opt">
	  <arg>-L</arg>
	  <arg>--list-files</arg>
	</group>
	<group choice="opt">
	  <arg>-m <replaceable>NAME</replaceable></arg>
	  <arg>--mkdir <replaceable>NAME</replaceable></arg>
	</group><sbr/>
	<group choice="opt">
	  <arg>-r <replaceable>NAME</replaceable></arg>
	  <arg>--rmdir <replaceable>NAME</replaceable></arg>
	</group>
	<group choice="opt">
	  <arg>-n</arg>
	  <arg>--num-files</arg>
	</group><sbr/>
	<group choice="opt">
	  <arg>-p <replaceable>RANGE</replaceable></arg>
	  <arg>--get-file <replaceable>RANGE</replaceable></arg>
	</group>
	<group choice="opt">
	  <arg>-P</arg>
	  <arg>--get-all-files</arg>
	</group><sbr/>
	<group choice="opt">
	  <arg>-t <replaceable>RANGE</replaceable></arg>
	  <arg>--get-thumbnail <replaceable>RANGE</replaceable></arg>
	</group><sbr/>
	<group choice="opt">
	  <arg>-T</arg>
	  <arg>--get-all-thumbnails</arg>
	</group><sbr/>
	<group choice="opt">
	  <arg>-r <replaceable>RANGE</replaceable></arg>
	  <arg>--get-raw-data <replaceable>RANGE</replaceable></arg>
	</group>
	<arg choice="opt">--get-all-raw-data</arg><sbr/>
	<arg choice="opt">--get-audio-data <replaceable>RANGE</replaceable></arg>
	<arg choice="opt">--get-all-audio-data</arg><sbr/>
	<group choice="opt">
	  <arg>-d <replaceable>RANGE</replaceable></arg>
	  <arg>--delete-file <replaceable>RANGE</replaceable></arg>
	</group>
	<group choice="opt">
	  <arg>-D</arg>
	  <arg>--delete-all-files</arg>
	</group><sbr/>
	<group choice="opt">
	  <arg>-u <replaceable>FILENAME</replaceable></arg>
	  <arg>--upload-file <replaceable>FILENAME</replaceable></arg>
	</group>
	<arg choice="opt">--capture-preview</arg><sbr/>
	<arg choice="opt">--capture-image</arg>
	<arg choice="opt">--capture-movie</arg>
	<arg choice="opt">--capture-sound</arg><sbr/>
	<arg choice="opt">--capture-show-info <replaceable>RANGE</replaceable></arg><sbr/>
	<arg choice="opt">--summary</arg>
	<arg choice="opt">--manual</arg>
	<arg choice="opt">--about</arg>
	<arg choice="opt">--shell</arg>
      </cmdsynopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>

      <para><xref linkend="libgphoto2"/> is a 
        cross-platform digital camera library, and
        <xref linkend="gphoto2-cli"/> is a command-line client for
        it.</para>

      <para>Where an option takes a range of files, thumbnails, or
       other data, they are numbered beginning at 1.  A range is a
       comma-separated list of numbers or spans
       (<quote><replaceable>first</replaceable>-<replaceable>last</replaceable></quote>).
       Ranges are XOR (exclusive or), so that <quote>1-5,3,7</quote>
       is equivalent to <quote>1,2,4,5,7</quote>.</para>

      <variablelist>
	<varlistentry>
	  <term><option>--debug</option></term>
	  <listitem>
	    <para>Turn on debugging.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-q</option>, <option>--quiet</option></term>
	  <listitem>
	    <para>Quiet output (default=verbose).</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-v</option>, <option>--version</option></term>
	  <listitem>
	    <para>Display version and exit.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-h</option>, <option>--help</option></term>
	  <listitem>
	    <para>Display a short usage message.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--list-cameras</option></term>
	  <listitem>
	    <para>List supported camera models.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--usb-usermap-script</option> <replaceable>NAME</replaceable></term>
	  <listitem>
	    <para>Use <replaceable>NAME</replaceable> as the hotplug usb script used in the output of <option>--print-usb-usermap</option>. Default is "usbcam".</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--print-usb-usermap</option></term>
	  <listitem>
	    <para>For every camera supported by your version of <command>gphoto2</command>, print the corresponding line for inclusion into the <filename>usb.usermap</filename> hotplug config file. The script name used in these lines is specified with the <option>--usb-usermap-script</option> option.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--list-ports</option></term>
	  <listitem>
	    <para>List supported port devices.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--stdout</option></term>
	  <listitem>
	    <para>Send file to stdout.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--stdout-size</option></term>
	  <listitem>
	    <para>Print filesize before data.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--auto-detect</option></term>
	  <listitem>
	    <para>List auto-detected cameras.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--port</option> <replaceable>PATH</replaceable></term>
	  <listitem>
	    <para>Specify port device.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--speed</option> <replaceable>SPEED</replaceable></term>
	  <listitem>
	    <para>Specify serial transfer speed.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--camera</option> <replaceable>MODEL</replaceable></term>
	  <listitem>
	    <para>Specify camera model.  Most model names contain
	     spaces: remember to enclose the name in quotes so that
	     the shell knows it is one parameter.  For example:
	     <userinput><option>--camera</option> "Kodak
	     DC240"</userinput>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--filename</option> <replaceable>FILENAME</replaceable></term>
	  <listitem>
	    <para>Specify a filename.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--usbid</option> <replaceable>USBID</replaceable></term>
	  <listitem>
	    <para>(Expert only) Override USB IDs.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-a</option>, <option>--abilities</option></term>
	  <listitem>
	    <para>Display camera abilities.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-f</option>, <option>--folder</option>
           <replaceable>FOLDER</replaceable></term>
	  <listitem>
	    <para>Specify camera folder (default="/").</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-R</option>, <option>--recurse</option></term>
	  <listitem>
	    <para>Recursion (default for download).</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--no-recurse</option></term>
	  <listitem>
	    <para>No recursion (default for deletion).</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-l</option>, <option>--list-folders</option></term>
	  <listitem>
	    <para>List folders in folder.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-L</option>, <option>--list-files</option></term>
	  <listitem>
	    <para>List files in folder.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-m</option>, <option>--mkdir</option>
	   <replaceable>NAME</replaceable></term>
	  <listitem>
	    <para>Create a directory.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-r</option>, <option>--rmdir</option>
	   <replaceable>NAME</replaceable></term>
	  <listitem>
	    <para>Remove a directory.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-n</option>, <option>--num-files</option></term>
	  <listitem>
	    <para>Display number of files.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-p</option>, <option>--get-file</option>
	   <replaceable>RANGE</replaceable></term>
	  <listitem>
	    <para>Get files given in range.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-P</option>, <option>--get-all-files</option></term>
	  <listitem>
	    <para>Get all files from folder.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-t</option>, <option>--get-thumbnail</option>
	   <replaceable>RANGE</replaceable></term>
	  <listitem>
	    <para>Get thumbnails given in range.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-T</option>, <option>--get-all-thumbnails</option></term>
	  <listitem>
	    <para>Get all thumbnails from folder.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-r</option>, <option>--get-raw-data</option>
	   <replaceable>RANGE</replaceable></term>
	  <listitem>
	    <para>Get raw data given in range.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--get-all-raw-data</option></term>
	  <listitem>
	    <para>Get all raw data from folder.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--get-audio-data</option>
	   <replaceable>RANGE</replaceable></term>
	  <listitem>
	    <para>Get audio data given in range.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--get-all-audio-data</option></term>
	  <listitem>
	    <para>Get all audio data from folder.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--delete-files</option>
	   <replaceable>RANGE</replaceable></term>
	  <listitem>
	    <para>Delete files given in range.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--delete-all-files</option></term>
	  <listitem>
	    <para>Delete all files in folder.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>-u</option>, <option>--upload-file</option>
	   <replaceable>FILENAME</replaceable></term>
	  <listitem>
	    <para>Upload a file to camera.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--capture-preview</option></term>
	  <listitem>
	    <para>Capture a quick preview.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--capture-image</option></term>
	  <listitem>
	    <para>Capture an image.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--capture-movie</option></term>
	  <listitem>
	    <para>Capture a movie.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--capture-sound</option></term>
	  <listitem>
	    <para>Capture an audio clip.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--show-info</option> <replaceable>RANGE</replaceable></term>
	  <listitem>
	    <para>Show info.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--summary</option></term>
	  <listitem>
	    <para>Summary of camera status.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--manual</option></term>
	  <listitem>
	    <para>Camera driver manual.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--about</option></term>
	  <listitem>
	    <para>About the camera driver.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><option>--shell</option></term>
	  <listitem>
	    <para>Start the gphoto2 shell, an interactive environment.
              See <link linkend="shell-mode">SHELL MODE</link><!--xref linkend="shell-mode"/--> for a detailed description.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect1>

    <refsect1 id="shell-mode">
      <title>Shell Mode</title>
      <para>The following commands are available:</para>
      
      <variablelist>
        <varlistentry>
          <term>cd</term>
          <listitem>
            <para>Change to a directory on the camera.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>lcd</term>
          <listitem>
            <para>Change to a directory on the local
              machine.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>exit, quit, q</term>
          <listitem>
            <para>Exit the gphoto2 shell.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>get</term>
          <listitem>
            <para>Download the file to the current directory.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>get-thumbnail</term>
          <listitem>
            <para>Download the thumbnail to the current directory.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>get-raw</term>
          <listitem>
            <para>Download raw data to the current directory.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>show-info</term>
          <listitem>
            <para>Show information.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>delete</term>
          <listitem>
            <para>Delete a file or directory.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>show-exif</term>
          <listitem>
            <para>Show EXIF information (only if compiled with
              EXIF support).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>help, ?</term>
          <listitem>
            <para>Displays command usage.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>ls</term>
          <listitem>
            <para>List the contents of the current directory on
              the camera.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect1>

    <refsect1>
      <title>See also</title>
      <para><xref linkend="libgphoto2"/>,
        <filename path="doc/">gphoto2.txt</filename>, 
        <filename path="doc/">gphoto2-cli.txt</filename>, 
        <ulink
               url="http://www.gphoto.org/">http://www.gphoto.org/</ulink> 
      </para>
    </refsect1>

    <refsect1>
      <title>Examples</title>
      <variablelist>
        <varlistentry>
          <term><userinput><command>gphoto2</command> <option>--list-files</option></userinput></term>
          <listitem>
            <para>List files on camera.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><userinput><command>gphoto2</command> <option>--get-file</option> <parameter>7-13</parameter></userinput></term>
          <listitem>
            <para>Get files number 7 through 13 from the list output by <userinput><command>gphoto2</command> <option>--list-files</option></userinput>.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><userinput><command>gphoto2</command> <option>--usb-usermap-script</option> <parameter>gphoto2cam</parameter> <option>--print-usb-usermap</option></userinput> >> <filename>/etc/hotplug/usb.usermap</filename></term>
          <listitem>
            <para>Append a line to the <command>hotplug</command> config file <filename>/etc/hotplug/usb.usermap</filename> for every supported camera, using <filename>/etc/hotplug/usb/gphoto2cam</filename> for setting up permissions correctly.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect1>

  </refentry>

  <refentry id="libgphoto2">
    <refentryinfo>
      <author><firstname>The gPhoto2</firstname><surname>Team</surname></author>
      <editor>
	<firstname>Hans Ulrich</firstname>
	<surname>Niedermann</surname>
	<affiliation>
	  <address><email>gp@n-dimensional.de</email></address>
	</affiliation>
      </editor>
    </refentryinfo>

    <refmeta>
      <refentrytitle>gphoto2</refentrytitle>
      <manvolnum>3</manvolnum>
    </refmeta>

    <refnamediv>
      <refname>gphoto2</refname>
      <refpurpose>cross-platform digital camera library</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <synopsis>#include &lt;gphoto2.h&gt;</synopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>
      <para>The <systemitem class="library">gphoto2</systemitem>
        library provides applications with access to a variety of
        cameras.</para>
      <para>This man page will be extended with autogenerated
        documentation of the interface types and methods used for
        communication between the 
        <systemitem class="library">gphoto2</systemitem> 
        library and a frontend.</para> 
    </refsect1>

    <refsect1>
      <title>Files</title>
      <variablelist>
        <varlistentry>
          <term><filename>~/.gphoto/settings</filename></term>
          <listitem>
            <para>Here
              <systemitem class="library">gphoto2</systemitem>
              applications may store their configuration used to
              access
              <systemitem class="library">gphoto2</systemitem>.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect1>

    <refsect1>
      <title>See also</title>
        <para><xref linkend="gphoto2-cli"/>,
          <xref linkend="libgphoto2_port"/>,
          <filename path="doc/">gphoto2.txt</filename>,
          <ulink
                 url="http://www.gphoto.org/">http://www.gphoto.org/</ulink> 
      </para>
    </refsect1>

  </refentry>

    <refentry id="libgphoto2_port">
      <refentryinfo>
        <author><firstname>The gPhoto2</firstname><surname>Team</surname></author>
        <editor>
          <firstname>Hans Ulrich</firstname>
          <surname>Niedermann</surname>
          <affiliation>
            <address><email>gp@n-dimensional.de</email></address>
          </affiliation>
        </editor>
      </refentryinfo>

      <refmeta>
        <refentrytitle>gphoto2_port</refentrytitle>
        <manvolnum>3</manvolnum>
      </refmeta>

      <refnamediv>
        <refname>gphoto2_port</refname>
        <refpurpose>cross-platform port access library</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <synopsis>#include &lt;gphoto2_port.h&gt;</synopsis>
      </refsynopsisdiv>

      <refsect1>
        <title>Description</title>
        <para>The 
          <systemitem class="library">libgphoto2_port</systemitem> 
          library was written to provide <xref linkend="libgphoto2"/>
          with a generic way of accessing ports. In this function, 
          <systemitem class="library">libgphoto2_port</systemitem> is the
          successor of the 
          <systemitem class="library">libgpio</systemitem> library.
        </para>
        <para>
          Currently, 
          <systemitem class="library">libgphoto2_port</systemitem> 
          supports serial (RS-232) and USB connections, the latter
          requiring 
          <systemitem class="library">libusb</systemitem>
          to be installed.
        </para>
        <para>
          The autogenerated API docs will be added here in the future.
        </para>
      </refsect1>

      <refsect1>
        <title>See also</title>
        <para><xref linkend="libgphoto2"/>,
          <filename path="doc/">gphoto2.txt</filename>,
          <ulink url="http://www.gphoto.org/">http://www.gphoto.org/</ulink>,
          <ulink url="http://libusb.sourceforge.net/">http://libusb.sourceforge.net/</ulink>
        </para>
      </refsect1>
    </refentry>

  </reference>

</book>

<!--
Local Variables:
mode: xml
sgml-indent-data: t
End:
-->