.TH XFM 1 "20 April, 2006" "xfm" XFM
.SH NAME
xfm \- X file and applications manager

.SH SYNOPSIS
.B xfm
[\fIoptions\fP ...]
.sp
.SH DESCRIPTION
\fIXfm\fP is a file and applications manager program for the X window system.
It provides virtually all of the features that you would expect in a file
manager \- move around your directory tree in multiple windows, move, copy or
delete files, and launch programs with simple mouse operations. Directory
displays are updated automatically in regular intervals when the contents of
the directory changes. The integrated application manager provides a kind of
``shelf'' onto which you can place your favorite applications, as well as the
files and directories you are currently working with. It also allows you to
access different groups of applications and files.  User-definable file types
let you specify a command to be executed when double-clicking on a file or
dropping other files onto it. Last not least, \fIxfm\fP can automatically
mount and unmount special devices like floppies as you open and close the
corresponding directories (mount points).
.SH "OPTIONS"
\fIXfm\fP accepts all the usual toolkit options. Furthermore, the following
options let you print \fIxfm\fP's version number and control which windows
should be displayed at startup.
.TP 4
.B \-version
Print the version number and exit.
.TP 4
.B \-appmgr
Only display the application manager window.
.TP 4
.B \-filemgr
Only display the file manager window. 
.PP
If both \fI\-appmgr\fP and \fI\-filemgr\fP are specified, then the
applications and one file manager window will be displayed, which is also
the default. If only \fI\-filemgr\fP is specified, the application manager will
not be available in this session.
.SH "USAGE"
Most of it should be fairly obvious. There is one application window and zero
or more file windows in which directories (also termed \fIfolders\fP) are
displayed. In order to perform an action, you either select items and then
invoke a menu operation, or you drag items from a file window to a second
(maybe the same) file window or the application window. You can also
double-click on an item to start a corresponding action (like launching an
application, editing a file, or changing directories), and press the right
menu button on an item to bring up a menu containing operations for a single
file or application.  Pressing the right button on the background of the
application window displays the application menu. File operations are accessed
from the file window menu bar as usual.
.PP
The left-hand mouse button selects an item (and deselects all others in the
same window). The second button toggles the selected state of an item.
.PP
A string containing the paths of the selected file items can be requested by
other applications using the standard selection mechanism (PRIMARY selection).
To provide visual feedback, the file window that owns the selection paints its
status line using a special highlight color. You can then paste the list of
selected files in some other window such as an xterm.
.PP
You can drag with the left-hand button to another window (or another icon, in
general a valid destination will be highlighted with a border when the cursor
is over it) to move files from one directory to another. The second button
used in the same way will copy files. You can also drag around items in the
application window; again, the left mouse button moves, and the second button
copies the selected items to a new position. Applications can be launched by
dropping files on them; and installing files and programs in the application
manager can be done by dropping files on the background of the application
window.  Finally, new file windows can be opened by simply dragging a
directory icon to the root window.
.PP
The action taken when double-clicking on a file depends on the type of the
file. If it is a directory, it is displayed in the file window. If it is an
executable, the program is started. Other files are opened in the default
editor (specified by the \fIeditor\fP resource), unless another action
is given in the \fIxfm_mailcap\fP file (see CONFIGURATION below).
.PP
The output of child processes invoked by \fIxfm\fP is captured in a special
log window. This window provides buttons for clearing the window contents and
for hiding the window. You can also specify whether you want the window to pop
up automagically when new output is available (\fIAuto Popup\fP option,
enabled by default), and explicitly show the window using the \fIShow log\fP
option of the \fIView\fP menu.
.PP
Directories can be displayed in three different forms: \fItree\fP (display
subdirectories in tree-like form), \fIicon\fP (display directories and files
as icons) and \fItext\fP (similar to \fIls \-l\fP). These options are selected
from the \fIView\fP menu. In the tree form, clicking on the arrows takes you
up or down one level.
.PP
Directory displays are updated automatically in regular intervals when the
contents of the directory changes. You can also explicitly request a folder
update by double-clicking on the directory name field of the corresponding
file window.
.PP
A menu of recently visited directories can be popped up by pressing the right
mouse button on the directory name field of the file window.
.SH "MENU COMMANDS"
Many menu operations can also be invoked with corresponding keyboard shortcuts
which can be changed by configuring the translations in the applications
defaults file accordingly. The default shortcuts, as defined in the
distributed application defaults file, are given in parentheses below.
.PP
FILE MENU
.PP
File manipulation operations.
.TP 4
.IR "New... " "(n)"
.br
Create a new (and empty) file.
.TP 4
.IR "Move... " "(m)"
.br
Rename a single item (directory or file) or move selected items to another
directory.
.TP 4
.IR "Copy... " "(c)"
.br
Create a copy of a single item under a new name or copy selected items to
another directory.
.TP 4
.IR "Link... " "(l)"
.br
Like \fICopy\fP, but creates symbolic links rather than copying the selected
items.
.TP 4
.IR "Delete " "(d, Del, Backspace)"
.br
Delete the selected items.
.TP 4
.IR "Select... " "(s)"
.br
Select items by pattern. The usual metacharacters are recognized (\fI*\fP,
\fI?\fP, \fI[ ]\fP). (Currently there is no provision for escaping these.)
.TP 4
.IR "Select all " "(a)"
.br
Select all items in the current directory (except the parent directory).
.TP 4
.IR "Deselect all " "(u)"
.br
Deselect all items.
.TP 4
.IR "Own Selection " "(o)"
.br
Request ownership of the PRIMARY selection. This is useful if some files had
been selected before but the ownership of the X-selection was lost and the
user later wants to get the ownership back.
.TP 4
.IR "Terminal " "(x)"
.br
Invokes an \fIx\-terminal\-emulator\fP(1) in the current directory (using the command
specified with the \fIdefaultXterm\fP resource).
.TP 4
.I "About xfm..."
.br
Display a box with some information about \fIxfm\fP.
.TP 4
.IR "Quit " "(q)"
.br
Terminate \fIxfm\fP.
.PP
FOLDER MENU
.PP
Operations dealing with directories and the file window.
.TP 4
.IR "New... " "(Shift+n)"
.br
Create a new directory.
.TP 4
.IR "Go to... " "(Shift+g)"
.br
Display the specified directory.
.TP 4
.IR "Home " "(Shift+h)"
.br
Display your home directory.
.TP 4
.IR "Up " "(Shift+u)"
.br
Display the parent directory.
.TP 4
.I Empty
.br
Delete all items in the current directory.
.TP 4
.IR "Clone " "(Shift+c)"
.br
Clone this file window (open another file window on the same directory).
.TP 4
.IR "Close " "(Shift+q)"
.br
Close this file window.
.PP
VIEW MENU
.PP
Options for the directory display and the log window.
.TP 4
.IR "Tree " "(Ctrl+r)"
.br
Select the tree form display.
.TP 4
.IR "Icons " "(Ctrl+i)"
.br
Select the icons form display.
.TP 4
.IR "Text " "(Ctrl+t)"
.br
Select the text form display. An additional \fIOption\fP menu appears which
allows you to select the information to be shown in the text view.
.TP 4
.IR "Sort by name " "(Ctrl+n)"
.br
Sort directory by name.
.TP 4
.IR "Sort by size " "(Ctrl+s)"
.br
Sort directory by size.
.TP 4
.IR "Sort by date " "(Ctrl+d)"
.br
Sort directory by date.
.TP 4
.IR "Filter... " "(Ctrl+f)"
.br
Specify a pattern to determine the files which should be displayed in the file
window. (This only affects normal files, i.e. directory items will not be
filtered. The \fIClear\fP button in the Filter dialog form reverts to the full
display.)
.TP 4
.IR "Hide folders " "(Ctrl+h)"
.br
Suppress directory items.
.TP 4
.IR "Mix folders/files " "(Ctrl+m)"
.br
Mix directories and other files.
.TP 4
.IR "Show hidden files " "(Ctrl+u)"
.br
Show hidden files (files starting with a dot).
.TP 4
.I Show log
.br
Redisplay the log window.
.PP
FILE POPUP MENU
.PP
Operations on a single file. This menu pops up when pressing the right mouse
button on a directory or file icon.
.TP 4
.I Open
Open a file window on the selected item. This option is only available if the
selected item is a directory.
.TP 4
.I Edit
.br
Edit the selected item using the program specified in the \fIeditor\fP
resource (only available if the selected item is not a directory).
.TP 4
.I View
.br
Same as Edit, but invokes a program for viewing the file (\fIdefaultViewer\fP
resource).
.TP 4
.I Rename...
.br
Rename the selected item (same as \fIMove\fP, but shows the current filename
as the default).
.TP 4
.I Move...
.br
Move the selected item.
.TP 4
.I Copy...
.br
Copy the selected item.
.TP 4
.I Link...
.br
Create a symbolic link.
.TP 4
.I Delete
.br
Delete the selected item.
.TP 4
.I Information...
.br
Display information about the selected item (file size, permissions and such).
.TP 4
.I Permissions...
.br
Change the permissions of the selected item.
.PP
APPLICATION MENU
.PP
Operations for managing the application window.
.TP 4
.I Install...
.br
Install a new application in the application window. Pops up a dialog form
into which you can enter the necessary information (see APPLICATION FILES for
a discussion of the fields in this form).
.TP 4
.I Install group...
.br
Simplified install dialog form for creating a new application group (see
APPLICATION FILES).
.TP 4
.I Cut
.br
Move the selected application items into a ``clip'' file (specified by the
\fIapplicationDataClip\fP resource). Together with the \fIPaste\fP option,
this allows you to move application items between different application
groups.
.TP 4
.I Copy
.br
Like \fIMove\fP, but simply copies the selected items instead of removing them
from the application window.
.TP 4
.I Paste
.br
Insert the contents of the clip file into the application window.
.TP 4
.I Delete
.br
Delete the selected items from the application window.
.TP 4
.I "About xfm..."
.br
Display a box with some information about \fIxfm\fP.
.TP 4
.I Quit
.br
Terminate \fIxfm\fP.
.PP
APPLICATION POPUP MENU
.PP
Operations on a single application item. This menu pops up when pressing the
right mouse button on an icon in the application window.
.TP 4
.I Edit...
.br
Edit an application item. Pops up a dialog form which allows you to change
the configuration information associated with the selected item (see
CONFIGURATION for a discussion of the fields in this form).
.TP 4
.I Cut
.br
Move the selected item to the clip file.
.TP 4
.I Copy
.br
Copy the selected item to the clip file.
.TP 4
.I Delete
.br
Delete the selected item from the application window.
.PP
APPLICATION WINDOW BUTTONS
.PP
These buttons at the bottom of the application window allow you to navigate in
the application group tree and open new file windows.
.TP 4
.I Back
.br
Return to the previous application group.
.TP 4
.I Main
.br
Return to the main application group (the one loaded at startup time).
.TP 4
.I Reload
.br
Reload the current application file. This option is useful to update the
contents of an application window after manual editing of the application
file.
.TP 4
.I File window
.br
Open a new file window on the user's home directory.
.SH "RESOURCES"
Various aspects of \fIxfm\fP can be configured by changing corresponding
resource settings in the application defaults file. Some important resources
are listed below:
.TP 4
.B highlightColor
.br
The color used for highlighting selected items, as well as the status line of
the file window which owns the primary selection (if any).
.TP 4
.B bitmapPath
.TP 4
.B pixmapPath
.br
The path on which to search for bitmap and pixmap icons, respectively.
.TP 4
.B iconPath
The path to look for pixmap icons for the file types.
.TP 4
.B applicationDataFile
.TP 4
.B devFile
.TP 4
.B magicFile
.br
The names of the application and configuration files used by \fIxfm\fP (see
CONFIGURATION). Normally, these files will be located in \fI~/.xfm\fP.
.TP 4
.B systemwideApplicationDataFile
.TP 4
.B systemwideDevFile
.TP 4
.B systemwideMagicFile
.br
These files are used, if the corresponding described before are not found.
This allows changeable system wide defaults while users are still
able to overwrite them.
.TP 4
.B applicationDataDir
.br
The directory in which the application files for new application groups are
located (see the \fIInstall group\fP option of the application menu), usually
\fI~/.xfm\fP. Application groups changed are also copied here, when the
original file cannot be written to.
.PP
If it does not exists, it will be generated when needed.
.TP 4
.B applicationDataClip
.br
The ``clip'' file used in Cut/Copy/Paste operations in the application window,
usually \fI~/.xfm/.XfmClip\fP.
.PP
If it begins with \fIapplicationDataDir\fP, this will be generated when
xfm starts.
.TP 4
.B doubleClickTime
.br
Set the time interval in milliseconds for which a sequence of two mouse clicks
should be interpreted as a double click. Default: 300.
.TP 4
.B updateInterval
.br
Set the time interval in milliseconds in which to perform automatic folder
updates. Default: 10000.
.TP 4
.B confirmXXX
.br
Resources to request confirmation for various operations. \fIXXX\fP can be
any one of \fIDeletes\fP, \fIDeleteFolder\fP, \fICopies\fP, \fIMoves\fP,
\fIOverwrite\fP and \fIQuit\fP. By default these are all enabled.
.TP 4
.B editor
.br
The command and leadings arguments with which \fIxfm\fP invokes your favorite editor.
.TP 4
.B viewer
.br
The command and leading arguments with which \fIxfm\fP invokes your favorite viewer.
.TP 4
.B xTerminal
.br
The command and leading arguments with which \fIxfm\fP starts a command within
and xterm.
(e.g. xterm \-e)
.TP 4
.B xTerminalAlone
.br
The command with which \fIxfm\fP runs an X terminal emulator.
(e.g. xterm)
.TP 4
.B shell
.br
Specifies the shell to use for running commands.
(If not set, \fB$SHELL\fP is used instead. If that also does not exists /bin/sh is used.)
.PP
There are way too many available resources to list them all in this manual
page, so please take a look at the application defaults file for more
information.
.SH "CONFIGURATION"
Besides the application resources, \fIxfm\fP can be configured by means of
four different files,
which are usually named
.IR xfm_dev ,
.IR xfm_magic ,
.I xfm_mime.types 
and
.IR xfm_mailcap ,
and are by default searched for in the
.IB ~ /.xfm
directory or in
.IR /etc/X11/xfm .
Moreover, there is
a number of so-called application files, from which \fIxfm\fP determines the
contents of the application window, like the \fIApps\fP file which usually
describes the contents of the main application group. All these files are
plain ASCII files which can be edited using any text editor. (Note that
application files are also written by \fIxfm\fP itself whenever the contents
of the application window changes.)  Any line in these files which starts with
a hash sign (\fI#\fP) is interpreted as a comment; empty lines are ignored.
.SH "MAGIC HEADERS"
\fIxfm\fP can determine
file types using the magic numbers contained in the files.
.PP
The magic numbers are described in a configuration file whose path is obtained
from the \fImagicFile\fP or \fIsystemwideMagicFile\fP resource, by default
.IB ~ /.xfm/xfm_magic
respectively
.BR /etc/X11/xfm/xfm_magic .
The format of the file is the same as that of the \fImagic\fP(5) file,
with some extensions described in \fIxfm_magic\fP(1).
The program \fIxfmtype\fP(5) can be used to test this.
.SH "SUFFIX TYPES"
If no file type could be obtained using the magic values,
\fIxfm\fP falls back to determine the type of a file by its suffix.
The rules it used are described in a configuration file whose path is obtained
from the \fImimeTypesFile\fP or \fIsystemwideMimeTypesFile\fP resource, by default
.IB ~ /.xfm/xfm_mime.types
respectively
.BR /etc/X11/xfm/xfm_mime.types .
The format of the file is described in the \fIxfm_mime.types\fP(5) man page.
.SH "OPENING FILES"
\fIxfm\fP determines how to open files consulting the file whose path is
obtained from the \fImailcapFile\fP or \fIsystemwideMailcapFile\fP resource,
by default
.IB ~ /.xfm/xfm_mailcap
respectively
.BR /etc/X11/xfm/xfm_mailcap .
The format of the file is described in the \fIxfm_mailcap\fP(5) man page.
.SH "DEVICE CONFIGURATION"
The device configuration file, \fIxfm_dev\fP, lets you specify which mount
points \fIxfm\fP should keep track of, and which actions to perform in order
to mount and unmount the corresponding file systems. This allows you to access
file systems on special devices such as floppies, CD-Roms, etc. in a
transparent way. See \fIxfm_dev\fP(5) for the format of this file.
.SH "APPLICATION FILES"
Application files are used to specify the contents of the application window.
Normally, these files are not altered with a text editor, but are updated by
\fIxfm\fP whenever the contents of the application window changes. An
understanding of the application data is necessary, however, if you want to
edit an existing or create a new entry using the \fIInstall\fP, \fIInstall
group\fP and \fIEdit\fP options of the application menu.
The format of those files is described in the \fIxfm\fP(5) man page.

\fIXfm\fP provides a number of operations which let you manipulate application
groups in a convenient manner. The items in the application window can be
moved and copied using drag and drop as usual. The \fICut\fP, \fICopy\fP and
\fIPaste\fP options of the application menu provide a means to move and copy
application items between different application files. Moreover, \fIxfm\fP
keeps a stack of application files loaded from a file or the application
window via a \fILOAD\fP action. The \fIBack\fP button at the bottom of the
application window lets you return to the previous group of applications, and
the \fIMain\fP button reloads your startup application file (and empties the
stack). Finally, the \fIInstall group\fP option of the application menu allows
you to create entries for new application groups easily. You only have to
specify the name of the group, the name of the corresponding application file,
and the name of the icon file.  The remaining fields of the entry are filled
in by \fIxfm\fP automatically.
.SH "FILES"
.TP 4
.IB ~ /.xfm
Standard location for \fIxfm\fP configuration and application files (see
CONFIGURATION above).
.TP 4
.B /etc/X11/xfm
Standard location for system wide configuration files used when no user
specific are available.
.SH "SEE ALSO"
.BR xfm (5),
.BR xfmmailcap (1),
.BR xfm_mailcap (5),
.BR xfmtype (1),
.BR X (1),
.BR xconsole (1),
.BR x\-terminal\-emulator (1),
.BR magic (5),
Arnaud Le Hors: \fBXPM Manual. The X PixMap Format\fP, Groupe Bull, 1993.
.SH "CAVEATS AND BUGS"
\fIXfm\fP catches the TERM signal to gracefully terminate the program,
unmounting all open file systems which have been mounted by \fIxfm\fP.
However, some window and session managers may not send TERM signals to their
client applications when terminating an X session. Therefore it might be
necessary to explicitly quit \fIxfm\fP or manually close file windows mounted
by \fIxfm\fP before exiting X.
.PP
Do not specify a relative path in the directory field of an application item,
because when you execute a push action on the application the current
directory might not always be what you expect. This will probably be fixed in
a future release. ;-)
.PP
Due to recent changes, it will propably no longer work with any shell
without a minimum of POSIX compatibility.
.SH "AUTHORS"
Simon Marlow (simonm@dcs.glasgow.ac.uk) from the University of Glasgow, Albert
Graef (ag@muwiinfa.geschichte.uni\-mainz.de) from the University of Mainz, and
Till Straumann (strauman@sun6hft.ee.tu\-berlin.de) from the Technical
University of Berlin, with help from many other people: Dave Safford
(dave.safford@edu.tamu.sc; automatic folder updates); Robert Vogelgesang
(vogelges@rhrk.uni\-kl.de; shell detection code); Juan D. Martin
(juando@cnm.us.es; magic headers); Kevin Rodgers
(rodgers@lvs\-emh.lvs.loral.com; Filter option); Scott Heavner
(sdh@falstaff.MAE.cwru.edu; View option); Brian King (ender@ee.WPI.EDU;
default values in parameter dialogs), Bernhard R. Link (brlink@debian.org;
various changes and responsible for the current state you see).