=head1 NAME

guestunmount - Unmount a guestmounted filesystem

=head1 SYNOPSIS

 guestunmount mountpoint

 guestunmount --fd=<FD> mountpoint

=head1 DESCRIPTION

guestunmount is a utility to clean up mounted filesystems
automatically.  L<guestmount(1)> mounts filesystems using libguestfs.
This program unmounts the filesystem when a program or script has finished
with it.

guestunmount is a wrapper around the FUSE L<fusermount(1)> program,
which must exist on the current C<PATH>.

There are two ways to use guestunmount.  When called as:

 guestunmount mountpoint

it unmounts C<mountpoint> immediately.

When called as:

 guestunmount --fd=FD mountpoint

it waits until the pipe C<FD> is closed.  This can be used to monitor
another process and clean up its mountpoint when that process exits,
as described below.

=head2 FROM PROGRAMS

You can just call C<guestunmount mountpoint> from the program, but a
more sophisticated way to use guestunmount is to have it monitor your
program so it can clean up the mount point if your program exits
unexpectedly.

In the program, create a pipe (eg. by calling L<pipe(2)>).  Let C<FD>
be the file descriptor number of the read side of the pipe
(ie. C<pipefd[0]>).

After mounting the filesystem with L<guestmount(1)> (on
C<mountpoint>), fork and run guestunmount like this:

 guestunmount --fd=FD mountpoint

Close the read side of the pipe in the parent process.

Now, when the write side of the pipe (ie. C<pipefd[1]>) is closed for
any reason, either explicitly or because the parent process
exits, guestunmount notices and unmounts the mountpoint.

If your operating system supports it, you should set the C<FD_CLOEXEC>
flag on the write side of the pipe.  This is so that other child
processes don't inherit the file descriptor and keep it open.

Guestunmount never daemonizes itself.

=head2 FROM SHELL SCRIPTS

Since bash doesn't provide a way to create an unnamed pipe, use a trap
to call guestunmount on exit like this:

 trap "guestunmount mountpoint" EXIT INT QUIT TERM

=head1 OPTIONS

=over 4

=item B<--fd=FD>

Specify the pipe file descriptor to monitor, and delay cleanup until
that pipe is closed.

=item B<--help>

Display brief help and exit.

=item B<-q>

=item B<--quiet>

Don’t display error messages from fusermount.  The return status is
still set (see L</EXIT STATUS> below).

=item B<--no-retry>

=item B<--retry=N>

By default, guestunmount will retry the fusermount operation up to
S<5 times> (that is, it will run it up to S<6 times> = S<1 try> +
S<5 retries>).

Use I<--no-retry> to make guestunmount run fusermount only once.

Use I<--retry=N> to make guestunmount retry C<N> times instead of 5.

guestunmount performs an exponential back-off between retries, waiting
S<1 second>, S<2 seconds>, S<4 seconds>, etc before each retry.

=item B<-V>

=item B<--version>

Display the program version and exit.

=back

=head1 ENVIRONMENT VARIABLES

=over 4

=item C<PATH>

The L<fusermount(1)> program (supplied by FUSE) must be available on
the current C<PATH>.

=back

=head1 EXIT STATUS

This program returns 0 if successful, or one of the following error
codes:

=over 4

=item C<1>

Program error, eg. could not allocate memory, could not run fusermount.
See the error message printed for more information.

=item C<2>

The mount point could not be unmounted even after retrying.  See
the error message printed for the underlying fusermount error.

=item C<3>

The mount point is not mounted.

=back

=head1 SEE ALSO

L<guestmount(1)>,
L<fusermount(1)>,
L<pipe(2)>,
L<guestfs(3)/MOUNT LOCAL>,
L<http://libguestfs.org/>,
L<http://fuse.sf.net/>.

=head1 AUTHORS

Richard W.M. Jones (C<rjones at redhat dot com>)

=head1 COPYRIGHT

Copyright (C) 2013 Red Hat Inc.