Provided by: fim_0.5~rc3-2build1_amd64 bug

NAME

       fim - fbi (linux framebuffer imageviewer) improved

SYNOPSIS

       fim [{options}] [--] {imagefile} [{imagefiles}]
       ... | fim [{options}] [--] [{imagefiles}] -
       fim [{options}] [--] [{files}] - < {file_name_list_text_file}
       fim --image-from-stdin [{options}] < {imagefile}
       fim --script-from-stdin [{options}] < {scriptfile}

DESCRIPTION

       fim is a `swiss army knife' for displaying image files.  It is capable of displaying image
       files using different graphical devices  while  offering  a  uniform  look  and  feel;  it
       features  an  internal  command  language specialized to the image viewing purposes; it is
       capable of interacting with standard input and output; the internal  command  language  is
       accessible  via  a command line capable of autocompletion and history; it features command
       recording, supports initialization files, customizable key  bindings,  internal  variables
       and  command  aliases,  vim-like  autocommands,  JPEG  comments,  EXIF  tags display, EXIF
       rotation/orientation, and much more.

       As a default, fim displays the specified file(s) on the detected  graphical  device  (e.g.
       with   SDL   if   X   is   detected,   or   the   linux   framebuffer   device   if  not).
       JPEG,PNG,GIF,BMP,TIFF,PPM,PGM,PBM,PCX formats are supported.  For 'XCF'  (Gimp's)  images,
       fim  will  try  to  use  'xcftopnm'.   For  '.FIG'  vectorial  images, fim will try to use
       'fig2dev'.  For '.DIA' vectorial images, fim will try to use 'dia'.  For '.SVG'  vectorial
       images,  fim  will  try  to  use  'inkscape'.   For  other  formats  fim  will  try to use
       ImageMagick's 'convert' executable.

       If {imagefile} is a directory, therein  contained  files  of  supported  formats  will  be
       loaded.  If  {imagefile} contains a trailing slash (/), it will be treated as a directory;
       otherwise a check will be made using stat(2). To change this default, see  description  of
       the _pushdir_re variable and the --no-stat-push and --recursive  options.

       If configured at build time, fim will be capable of using SDL or aalib output.

       This  man  page  only describes the fim command line options.  See man fimrc(5) for a full
       specification of the fim language, commands, variables, and an example configuration file.

USAGE

       You may invoke fim from an interactive shell and control it  with  the  keyboard,  as  you
       would do with any image viewer with reasonable key bindings.

       fim  is keyboard oriented: there are no user menus or buttons available.  If you need some
       feature or setting which is not accessible from the default  keyboard  configuration,  you
       probably  need  a custom configuration or simply need to type a custom command. For these,
       you can use the internal command and configuration language.  The full  specification  for
       these is accessible at runtime using the internal help system (typing :help).

OPTIONS

       Accepted command line {options} :

       --     The  arguments  before -- beginning with - will be treated as command line options.
              All arguments after -- will be treated as filenames regardlessly.

       -a, --autozoom
              Enable autozoom.  fim will automagically pick a reasonable zoom factor when loading
              a new image (as in fbi).

       -b, --binary[=24|1]
              Display  (any  filetype)  binary  files  contents as they were raw 24 or 1 bits per
              pixel pixelmaps.  Will  arrange  the  image  by  rows  long  as  specified  by  the
              _preferred_rendering_width  variable  for  the image width (unless a narrower image
              suffices).  Regard this as an easter bunny option.

       --as-text
              Display (any filetype) files contents as they were text.  Will only show  printable
              characters.  Regard this as an easter bunny option.

       --cd-and-readdir
              Step into the first loaded file directory and push other files.

       -c {commands}, --execute-commands {commands}
              The  commands string will be executed before entering the interactive loop.  Please
              note that if your commands are more complicated than a simple 'next' or  'pornview'
              command, they must be quoted and escaped in a manner suitable for your shell!

              For  example,  -c  '*2;2pan_up;display;while(1){align  "bottom";sleep  "1"  ; align
              "top"}' (with the single quotes) will tell fim to first double the displayed  image
              size,  then  pan two times up, then display the image ; and then do an endless loop
              consisting of bottom and top aligning, alternated.

       -C {commands}, --execute-commands-early {commands}
              Just as the --execute-commands option, but commands will  be  executed  before  the
              loading of any config file.

              For example, -C '_scale_style=" "' will make fim start with no auto-scaling.

       -d {framebuffer device}, --device {framebuffer device}
              Framebuffer device to use. Default is the one your vc is mapped to (as in fbi).

       --dump-reference-help[=man].
              Will dump to stdout the language reference help.

       -D, --dump-default-fimrc
              The  default  configuration  (the one hardcoded in the fim executable) is dumped on
              standard output and fim exits.

       -E {scriptfile}, --execute-script {scriptfile}
              The scriptfile will be executed right after  the  default  initialization  file  is
              executed.

       -f {fimrc}, --etc-fimrc {fimrc}
              Specify    an    alternative    system    wide    initialization   file   (default:
              /usr/local/etc/fimrc), which will be executed  prior  to  any  other  configuration
              file.

       -F {commands}, --final-commands {commands}
              The  commands  string  will  be  executed after exiting the interactive loop of the
              program (right before terminating the program).

       -h, --help[=s|d|l|m]
                         Print (short, descriptive, long, or  complete  man)  program  invocation
              help, and terminate.

       --load-image-descriptions-file {filename}
              Load  image descriptions from {filename}. In {filename} each line is the name of an
              image  file  (its  basename  will  be  taken),  then  a   Tab   character   (unless
              --image-descriptions-file-separator  specifies  otherwise),  then  the  description
              text. Each description will be put in the _comment variable of the  image  at  load
              time.  Will override the comment eventually loaded from the file (e.g. JPEG, PNG or
              TIFF comment). Special comment lines like "#!fim:var=val" will  lead  i:var  to  be
              assigned  value  val  (unquoted)  at  image loading time. Special description lines
              begin with markers:  with "#!fim:=" the last description  line  to  be  used;  with
              "#!fim:+"  what  follows  +  will  be  appended  to the last description line; with
              "#!fim:^" what follows ^ will be prepended  to  the  last  description  line;  with
              "#!fim:s/f/t"  the  last description line will be used, but occurrences of string f
              will be substituted with string t (f and t can contain anything but not  a  /).  If
              val  is  empty  that  variable will be unset. These variables are stored also in an
              internal index used by the limit command. This option  sets  _caption_over_image=2,
              so that a caption will be displayed over the image.

       --image-descriptions-file-separator {sepchar}
              A character to be used as a separator between the filename and the description part
              of lines specified just before a --load-image-descriptions-file.

       -i, --image-from-stdin
              Will read one single image from  the  standard  input  (the  image  data,  not  the
              filename).   May not work with all supported file formats.  In the image list, this
              image will be displayed as "<STDIN>".

       -m {vmode}, --mode {vmode}
              Name of the video mode to  use  video  mode  (must  be  listed  in  /etc/fb.modes).
              Default  is  not  to  change  the  video  mode.   In the past, the XF86 config file
              (/etc/X11/XF86Config) used to contain Modeline information, which could be  fed  to
              the  modeline2fb  perl  script (distributed with fbset).  On many modern xorg based
              systems, there is no direct way to obtain a fb.modes file from the xorg.conf  file.
              So instead one could obtain useful fb.modes info by using the (fbmodes (no man page
              AFAIK)) tool, written by bisqwit.  An unsupported mode should make  fim  exit  with
              failure.   But  it  is possible the kernel could trick fim and set a supported mode
              automatically, thus ignoring the user set mode.

       -N, --no-rc-file
              No personal initialization file will be read (default is ~/.fimrc) at startup.

       --no-etc-rc-file
              No system wide initialization file will be read (default  is  /usr/local/etc/fimrc)
              at startup.

       --no-internal-config
              No   internal   default   configuration   at   startup   (uses   internal  variable
              _no_default_configuration). Will only provide a minimal working configuration.

       --no-commandline
              With internal command line mode disabled.

       --no-history-save
              Do  not  save  execution  history   at   finalization   (uses   internal   variable
              _save_fim_history).

       --no-history-load
              Do not load execution history at startup.

       --no-history
              Do not load or save execution history at startup.

       -p, --script-from-stdin
              Will read commands from stdin prior to entering in interactive mode.

       -o [fb|sdl|aa|imlib2|caca|dumb], --output-device [fb|sdl|aa|imlib2|caca|dumb]
              Will  use  the  specified  device  as fim video output device, overriding automatic
              checks.The available  devices  depend  on  the  original  configuration/compilation
              options,  so  you  should  get  the  list  of  available output devices issuing fim
              --version.  The aa option may be specified  as   aa={['w']}  ;  the  'w'  character
              allows  windowed  mode  in  case  of  aalib running under X (otherwise, the DISPLAY
              environment variable will be unset for the  current  instance  of  fim).   The  sdl
              option  may  be  specified  as   sdl={['w']['m']['r']['W']['M']['R']width:height} ,
              where width is and height are integer numbers specifying  the  desired  resolution;
              the  'w' character requests windowed mode; the 'm' character requests mouse pointer
              display; the 'r' character requests support for window  resize;  the  same  letters
              uppercase request explicit negation of the mentioned features.

       --offset {bytes-offset[{:upper-offset}|{+offset-range}]}
              Will  use  the  specified  offset  (in  bytes)  for opening the specified files. If
              :upper-offset is specified, further bytes until upper-offset  will  be  probed.  If
              +offset-range is specified instead, that many additional bytes will be probed.  Use
              this option to search damaged file systems for image files.

       -P, --text-reading
              Enable textreading mode.  This has the effect that fim will display  images  scaled
              to  the  width of the screen, and aligned to the top.  Useful if the images you are
              watching text pages, all you have to do to get the next piece of text is  to  press
              space (in the default key configuration, of course).

       -s {value}, --scroll {value}
              Set scroll steps for internal variable _steps (default is 20%).

       --slideshow {number}
              Interruptible  slideshow  mode;  will wait for {number} of seconds (assigned to the
              _want_sleep_seconds  variable  after  each  loading;   implemented   by   executing
              while(_fileindex<_filelistlen){sleep   _want_sleep_seconds;   next;}   as  a  first
              command.

       -S, --sanity-check
              A quick sanity check before starting the interactive fim execution, but  after  the
              initialization.

       -t, --no-framebuffer
              Fim  will  not use the framebuffer but the aalib (ASCII art) driver instead (if you
              are curious, see (info aalib)).  If aalib was not enabled at tompile time, fim will
              work without displaying images at all.

       -T {terminal}, --vt {terminal}
              The  terminal  will be used as virtual terminal device file (as in fbi).  See (chvt
              (1)), (openvt (1)) for more info about this.  Use (con2fb (1)) to map a terminal to
              a framebuffer device.

       --sort Sort files list before browsing according to full filename.

       --sort-basename
              Sort files list before browsing according to file basename's.

       -u, --random
              Randomly  shuffle  the  files  list  before  browsing  (seed  depending  on  time()
              function).

       --random-no-seed
              Randomly shuffle the files list before browsing (no seeding).

       -v, --verbose
              Be verbose: show status bar.

       -V, --version
              Display  program  version,  compile  flags,  enabled  features,  linked   libraries
              information, supported filetypes/file loaders, and then terminate.

       -w, --autowidth
              Scale the image according to the screen width.

       --no-auto-scale
              Do not scale the images after loading (will set '_scale_style=" "';).

       --autowindow
              Will  resize  the window size (if supported) to the image size. Don't use this with
              other image scaling options.

       --no-stat-push
              Sets _push_checks=0 before initialization, thus disabling file/dir existence checks
              with stat(2) at push push time (and speeding up startup).

       -H, --autoheight
              Scale the image according to the screen height.

       -W {scriptfile}, --write-scriptout {scriptfile}
              All  the  characters  that you type are recorded in the file {scriptout}, until you
              exit Fim.  This is  useful  if  you want to create a script file to  be  used  with
              "fim  -c"  or  ":exec"  (analogous to Vim's -s and ":source!").  If the {scriptout}
              file exists, it will be not touched (as in Vim's -w).

       -, --read-from-stdin
              Read file list from stdin: each line one file.

              Note that these the three standard input  reading  functionalities  (-i,-p  and  -)
              conflict  :  if  two or more of them occur in fim invocation, fim will exit with an
              error and warn about the ambiguity.

              See the section INVOCATION EXAMPLES below to read some useful (and unique) ways  of
              employing fim.

       --read-from-stdin-elds <arg>
              Specify    an    endline   delimiter   string   for   breaking   lines   read   via
              -/--read-from-stdin. Line text before the delimiter will be  treated  as  names  of
              files  to load; the text after will be ignored until a newline. This is useful e.g.
              to description files as filename list files.

       -A, --autotop
                         Align images to the top (UNFINISHED).

       -q, --quiet
              Quiet mode. Sets _display_status=0;_display_busy=0;.

       -r {resolution}, --resolution {resolution}
                         Set resolution (UNFINISHED).

       -R, --recursive
                         Push files/directories to the files list recursively.

PROGRAM RETURN STATUS

       The  program  return  status  is  0  on  correct  operation;  252  on  unsupported  device
       specification;  248 on bad input; 255 on a generic error; 42 on a signal-triggered program
       exit;  or a different value in case of an another error.
        The return status may be controlled by the use of the quit command.

COMMON KEYS AND COMMANDS

       The following keys and commands are hardcoded in the minimal configuration. These are working by default before any config loading, and before the hardcoded config loading (see variable _fim_default_config_file_contents).

        n    goto '+1f'
        p    goto '-1f'
        +    magnify
        -    reduce
        h    pan 'left'
        l    pan 'right'
        k    pan 'up'
        j    pan 'down'
        q    quit
       You can type a number before a command binding to iterate the assigned command:
       3k    3pan 'up'

       :       enter command line mode
       :{number}       jump to {number}^th image in the list
       :^           jump to first image in the list
       :$           jump to last image in the list
       :*{factor}      scale the image by {factor}
       :{scale}%       scale the image to the desired {scale}
       :+{scale}%       scale the image up to the desired percentage {scale} (relatively to the original)
       :-{scale}%       scale the image down to the desired percentage {scale} (relatively to the original)

       /{regexp}       entering the pattern {regexp} (with /) makes fim jump to the next image whose filename matches {regexp}
       /*.png$         entering this pattern (with /) makes fim jump to the next image whose filename ends with 'png'
       /png       a shortcut for /.*png.*

       !{syscmd}      executes the {syscmd} quoted string as a "/bin/sh" shell command

       You can visualize all of the default bindings invoking fim --dump-default-fimrc | grep bind .
       You can visualize all of the default aliases invoking fim  --dump-default-fimrc | grep alias .

       The Return vs. Space key thing can be used to create  a  file  list  while  reviewing  the
       images and use the list for batch processing later on.

       All  of  the  key  bindings are reconfigurable; see the default fimrc file for examples on
       this, or read the complete manual: the FIM.TXT file distributed with fim.

AFFECTING ENVIRONMENT VARIABLES

       FBFONT         (just like in fbi) a Linux consolefont font file.
       If using a gzipped font, the zcat program will be used to uncompress it (via execvp(3)).
       If not specified, the following files will be probed and the first existing will be selected:

       /usr/share/consolefonts/Uni3-TerminusBoldVGA14.psf.gz
       /usr/lib/kbd/consolefonts/lat9-16.psf.gz
       /usr/share/consolefonts/lat1-16.psf
       /usr/share/consolefonts/lat1-16.psf.gz
       /usr/share/consolefonts/lat1-16.psfu.gz
       /usr/share/kbd/consolefonts/lat1-16.psf
       /usr/share/kbd/consolefonts/lat1-16.psf.gz
       /usr/share/kbd/consolefonts/lat1-16.psfu.gz
       /usr/lib/kbd/consolefonts/lat1-16.psf
       /usr/lib/kbd/consolefonts/lat1-16.psf.gz
       /usr/lib/kbd/consolefonts/lat1-16.psfu.gz
       /lib/kbd/consolefonts/lat1-16.psf
       /lib/kbd/consolefonts/lat1-16.psf.gz
       /lib/kbd/consolefonts/lat1-16.psfu.gz
       /lib/kbd/consolefonts/Lat2-VGA14.psf.gz
       /lib/kbd/consolefonts/Lat2-VGA16.psf.gz
       /lib/kbd/consolefonts/Lat2-VGA8.psf.gz
       /lib/kbd/consolefonts/Uni2-VGA16.psf.gz
       /usr/share/consolefonts/default8x16.psf.gz
       /usr/share/consolefonts/default8x9.psf.gz
       /usr/share/consolefonts/Lat15-Fixed16.psf.gz
       /usr/share/consolefonts/default.psf.gz
       fim://

       If the special fim:// string is specified, a hardcoded font will be used.
       FBGAMMA        (just like in fbi) gamma correction (applies to dithered 8 bit mode only). Default is 1.0.
       FRAMEBUFFER    (just like in fbi) user set framebuffer device file (applies only to the fb mode).
       If unset, fim will probe for /dev/fb0.
       TERM      (only in fim) will influence the output device selection algorithm, especially if $TERM=="screen".
       DISPLAY   If this variable is set, then the sdl driver will be probed by default.

COMMON PROBLEMS

       fim needs read-write access to the framebuffer devices (/dev/fbN or  /dev/fb/N),  i.e  you
       (our  your  admin)  have  to make sure fim can open the devices in rw mode.  The IMHO most
       elegant way is to use pam_console (see /etc/security/console.perms) to chown  the  devices
       to  the  user  logged  in  on the console.  Another way is to create some group, chown the
       special files to that group and put the users which are allowed  to  use  the  framebuffer
       device  into  the group.  You can also make the special files world writable, but be aware
       of the security implications this has.  On a private box it might be  fine  to  handle  it
       this way through.

       If  using  udev,  you can edit : /etc/udev/permissions.d/50-udev.permissions and set these
       lines like here :
        # fb devices
        fb:root:root:0600
        fb[0-9]*:root:root:0600
        fb/*:root:root:0600

       fim also needs access to the linux  console  (i.e.  /dev/ttyN)  for  sane  console  switch
       handling.   That  is obviously no problem for console logins, but any kind of a pseudo tty
       (xterm, ssh, screen, ...) will not work.

INVOCATION EXAMPLES

       fim media/
       # Will load files from the directory media.

       fim -R media/ --sort
       # Will open files found by recursive traversal of directory media, then sorting the list.

       find /mnt/media/ -name *.jpg | fim -
       # Will make fim read the file list from standard input.

       find /mnt/media/ -name *.jpg | shuf | fim -
       # will make fim read the file list from standard input, randomly shuffled.

       cat script.fim | fim -p images/*
       # Will make fim read the script file script.fim from standard input  prior  to  displaying
       files in the directory images

       scanimage ... | tee scan.ppm | fim -i
       # Will make fim read the image scanned from a flatbed scanner as soon as it is read

       fim * > selection.txt
       # Will output the file names marked interactively with the 'list "mark"' command in fim to
       a file.

       fim * | fim -
       # will output the file names marked with 'm' in fim to a second instance of fim, in  which
       these could be marked again.

       fim -c 'pread "vgrabbj -d /dev/video0 -o png";reload'
       # will display an image grabbed from a webcam.

       fim -o aa -c 'pread "vgrabbj -d /dev/video0 -o png";reload;system "fbgrab" "asciime.png"'
       # if running in framebuffer mode, will save a png screenshot with an ASCII rendering of an
       image grabbed from a webcam.

       fim -c 'while(1){pread "vgrabbj -d /dev/video0 -o png";reload;sleep 1;};'
       # will display a sequence of images grabbed from a webcam; circa 1 per second.

NOTES

       This manual page is neither accurate nor complete. In particular, issues related to driver
       selection  shall  be described more accurately. Also the accurate sequence of autocommands
       execution,  variables  application  is  critical  to  understanding  fim,  and  should  be
       documented.   The filename "<STDIN>" is reserved for images read from standard input (view
       this as a limitation), and thus handling files with such name may  incur  in  limitations.
       The  SDL  driver  is  quite  inefficient,  for  a  variety  of reasons. In particular, its
       interaction with the readline library can be problematic (e.g.: when running in  sdl  mode
       without a terminal). This shall be fixed.

BUGS

       fim has bugs. Please read the BUGS file shipped in the documentation directory to discover
       the known ones.

FILES

       /usr/local/share/doc/fim
                      The directory with Fim documentation files.

       /usr/local/etc/fimrc
                      The system  wide  Fim  initialization  file  (executed  at  startup,  after
                      executing the hardcoded configuration).

       ~/.fimrc       The personal Fim initialization file (executed at startup, after the system
                      wide initialization file).

       ~/.inputrc     If Fim is built with GNU readline support, it will be susceptible to chages
                      in  the  user set ~/.inputrc configuration file contents.  For details, see
                      (man readline(3)).

SEE ALSO

       Other Fim man pages: fimgs(1), fimrc(1).
       Or related programs:  fbset(1),  con2fb(1),  convert(1),  vim(1),  fb.modes(8),  fbset(8),
       fbgrab(1), fbdev(4), setfont(8), xfs(1).

AUTHOR

       Michele Martone <dezperado _CUT_ autistici _CUT_ org> is the author of fim, "fbi improved".

COPYRIGHT

       Copyright (C) 2007-2016 Michele Martone <dezperado _CUT_ autistici _CUT_ org> (author of fim)
       Copyright  (C)  1999-2004 Gerd Hoffmann <kraxel _CUT_ bytesex.org> is the author of "fbi",
       upon which fim was originally based.

       This program is free software; you can redistribute it and/or modify it under the terms of
       the  GNU  General  Public  License  as  published  by the Free Software Foundation; either
       version 2 of the License, or (at your option) any later version.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY  WARRANTY;
       without  even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
       See the GNU General Public License for more details.

       You should have received a copy of the GNU General Public License along with this program;
       if  not,  write  to  the  Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
       Boston, MA 02110-1301 USA.

                                  (c) 2007-2016 Michele Martone                            fim(1)