unieject: Universal Eject command
---------------------------------

This package consists of a library and a command line tool which uses that lib.

libunieject is a library which allows the linked software to perform
automatic ejects and unmounting the filesystems for the device you
want to eject.

This is now API-stable, and the public API will be maintained in newer version
by using linker scripts if needed. No non-public symbols are exported, so there
are no chances that internal API changes will break programs linked to this.

The command line tool instead is a mimic of classic eject command for Linux
( http://eject.sourceforge.net/ ), which supports also the features of
FreeBSD's eject command ( http://www.freshports.org/sysutils/eject/ ).

It hasn't a complete syntax compatibility with either Linux's or FreeBSD's
ejects as they have conflicts between them, but the main options are the
same.

It can fully replace FreeBSD's eject (in both atapi and atapicam mode), and
already mime the main options of Linux's eject.

Dependencies
------------

libcdio (version 0.74 or above) http://www.gnu.org/software/libcdio/
  The base library that provides access to CD-Rom drives. Mandatory.
  FreeBSD support requires at least version 0.76 to handle ATAPI
  CD-Roms without CAM support.

glib (2.6 or later) http://www.gtk.org/
  This library (quite common on Linux and other Free operating
  systems) provide support for option parsing (replaces popt that was
  used before) and message logging capabilities.

libconfuse (2.5) http://www.nongnu.org/confuse/
  Used for configuration file parsing. Optional, it can be disabled with
  --without-libconfuse option at ./configure, in which case the configuration
  file won't be loaded and parsed at all.

GIT
  Required to get an updated ChangeLog built during make dist phase.
  Optional when building out of the source tarball.

libxslt
  xsltproc command is used by the man pages regeneration together with
  the DocBook XSL-NS stylesheets package.
  It is only used during make dist phase, so it's not needed to
  compile the package from the released tarballs.

Compiler
  unieject is tested with GCC 3.3 through 4.4. It should work fine
  with ICC9, too. To work it requires the destructor attribute that
  are present in GCC since version 3, and in ICC 9 (at least).  If
  supported, it will also make use of other attributes to hide symbols
  from the resulting library (right now, just GCC, support for ICC
  requires to be worked on).

OS-specific notes
-----------------
Although libcdio masks most of the underlying operating system's calls, to work
as intended, unieject has to use some workarounds on certain OS:

FreeBSD
  - When accessing CD-Rom devices via CAM interface, the capabilities are
    unset as there is no way to get them directly. They are then ignored, and
    set as the drive is capable of everything.
  - Before ejecting a CD-Rom, the CDIOCALLOW ioctl must be sent to the device.
  - Ejecting an ATAPI CD-Rom device without using CAM interface is done with
    raw ioctls.

Linux
  - The MMC to lock the CD-Rom door is disallowed from userspace, so the lock
    is done using raw ioctls. The workaround is enabled during configure by
    --enable-lock-workaround, so that it can be disabled if this will change
    in future.

Note to packagers
-----------------
Being a package maintainer myself, I think it's good to leave a few notes to
who wants to package unieject.

Unieject is though as a drop-in replacement for 'eject' command, but still it
doesn't just "go in" as is, because programs just know about 'eject' command.
If you want to make unieject provide the eject facilities to other programs
you need to create an eject symlink to unieject so that eject command is
executed by unieject.
Please also note that to be able to umount correctly the partitions you must
be root, or use a suid wrapper. You can also set capabilities bits to eject
command, but that's still not supported. The use of a suid umount wrapper like
pumount is supported by the configuration file.

The sample configuration file is not installed by default, this allow to define
the right unieject defaults on a per-distribution basis.

API documentation is not being built at the moment; when it will be, it will be
specified and will have a --enable/--disable switch on ./configure.

This package is supposed to build fine with -Werror, -Wall, -Wextra and 
-pedantic CFLAGS, or at least it does so on my system. Unfortunately, its
./configure to fail when checking for strdup if -Werror is defined, I don't
really know why. Also the --as-needed linker flag is supposed to work.

A better way to blend in unieject with pmount is to install unieject as suid and
in plugdev group, exactly as pmount, and then set it to use the pumount command
for unmounting.

API Documentation
-----------------
libunieject is quite simple as a library, but it has some documentation about
the libraries it provides.
The API documentation can be built using doxygen. The configure script will
automatically take care of looking for doxygen and, if it's found, to expand
a Doxyfile with the path of the source code and the output directory that would
be $(top_builddir)/doc.
The formats which you want the documentation into can be selected passing to
configure a DOXYFORMATS with the name of the formats to enable.

Note: --enable-doc does *not* mean that the doc is going to be built by make
and installed by make install. Building and installing the documentation is
something that should be done only by the users (or packagers) who really
wants and know how to use the API documentation.