Debian Codegraph @

doc/fim.man.in

raw
1 .\"
2 .\" $Id$
3 .\"
4 .TH FIM 1 "(c) 2007-2024 Michele Martone"
5 .SH NAME
6 fim - \fBF\fPbi (linux \fBf\fPrame\fBb\fPuffer \fBi\fPmageviewer) \fBIM\fPproved, an universal image viewer
7 .SH SYNOPSIS
8 .B fim
9 [\fR\fI{options}\fR] [--] \fR\fI{imagepath}\fR [\fR\fI{imagepaths}\fR]
10 .br
11 .B fim
12 --output-device [fb|sdl|gtk|ca|aa|dumb][=\fR\fI{gfxopts}\fR]
13 .br
14 .B ... | fim
15 [\fR\fI{options}\fR] [--] [\fR\fI{imagepaths}\fR] -
16 .br
17 .B fim
18 [\fR\fI{options}\fR] [--] [\fR\fI{files}\fR] - < \fR\fI{file_name_list_text_file}\fR
19 .br
20 .B fim
21 --image-from-stdin [\fR\fI{options}\fR] < \fR\fI{imagefile}\fR
22 .br
23 .B fim
24 --script-from-stdin [\fR\fI{options}\fR] < \fR\fI{scriptfile}\fR
25 .br
26 .B fim
27 --help[=s|d|l|m] [\fR\fI{help-item}\fR ...]
28 .br
29
30 .SH DESCRIPTION
31 .B
32 fim
33 is a `swiss army knife' for displaying image files.
34 It is capable of displaying image files using different graphical devices while offering a uniform look and feel.
35 Key bindings are customizable and specified in an initialization file.
36 Interaction with standard input and output is possible, especially in shell scripts.
37 An internal scripting language specialized for image viewing allows image navigation, scaling, manipulation of internal variables, command aliases, and Vim-like autocommands.
38 The internal language can be interacted with via a command line mode capable of autocompletion and history (the readline mode).
39 Further features are display of EXIF tags, JPEG comments, EXIF rotation/orientation, load of "description files", faster load via image caching, command recording, and much more.
40
41 As a default,
42 .B
43 fim
44 displays the specified file(s) on the detected, most convenient graphical device. This can be with SDL if running under X, an ASCII-art driver (aalib or libcaca) if running behind ssh without X forwarding, or the linux framebuffer device. Graphical file formats BMP, PCX are supported natively, while JPEG, PNG, GIF, TIFF, PPM, PGM, PBM, QOI, AVIF, WEBP are supported via third party libraries.
45 Further formats are supported via external converters.
46 For XCF (Gimp's) images, 'xcftopnm' or 'xcf2pnm' is used.
47 For FIG vectorial images, 'fig2dev' is used.
48 For DIA vectorial images, 'dia' is used.
49 For NEF raw camera images, 'dcraw' is used.
50 For SVG vectorial images, 'inkscape' is used.
51 For other formats ImageMagick's 'convert' is used.
52 The converter is given 15 seconds for the conversion before a timeout.
53
54
55 If \fR\fI{imagepath}\fR is a file, its format is guessed not by its name but by its contents. See the \fB_file_loader\fP variable to change this default.
56
57
58 If \fR\fI{imagepath}\fR is a directory, load files of supported formats contained there. If \fR\fI{imagepath}\fR contains a trailing slash (/), it is treated as a directory; otherwise that is checked via \fBstat(2)\fP. To change this default, see description of the \fB_pushdir_re\fP variable and the \fB--no-stat-push\fP and \fB--recursive\fP options.
59
60 This man page describes
61 .B fim
62 command line options and usage.
63 See man \fR\fIfimrc\fR(5) for a full specification of the
64 .B
65 fim
66 language, commands, keysyms, autocommands, variables, aliases, examples for a configuration file and readline usage samples.
67
68 .SH USAGE
69 You may invoke
70 .B
71 fim
72 from an interactive shell and control it with the keyboard, as you would do with any image viewer with reasonable key bindings.
73
74 .B
75 fim
76 is keyboard oriented: there are no user menus or buttons available.
77 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.
78
79 See options \fB--read-from-stdin\fP, \fB--script-from-stdin\fP, and \fB--image-from-stdin\fP for more script-oriented usages.
80
81 The full commands specification is also accessible at runtime using the internal help system (typing :help).
82
83
84 .SH OPTIONS
85 Accepted command line \fB\fR\fI{options}\fR\fP:
86 .TP
87 \fB--\fP
88 Treat arguments after \fB--\fP
89 as filenames.
90 Treat arguments before \fB--\fP
91 as command line options if these begin with
92 \fB-\fP,
93 and as filenames otherwise.
94
95 .TP
96 \fB-a\fP, \fB--autozoom\fP
97 Enable autozoom. Automagically pick a reasonable zoom factor when displaying a new image (as in \fBfbi\fP).
98 .TP
99 \fB-b[24|1]\fP, \fB--binary[=24|1]\fP
100 Display contents of binary files (of any filetype) as these were raw 24 or 1 bits per pixel pixelmaps.
101 The width of this image will not exceed the value of the \fB_preferred_rendering_width\fP variable.
102 Regard this as an easter bunny option.
103
104 .TP
105 \fB--as-text\fP
106 Display contents of files (of any filetype) as these were text.
107 The width of this image will not exceed the value of the \fB_preferred_rendering_width\fP variable.
108 Non-printable characters are then displayed as " ".
109 Regard this as another easter bunny option.
110
111 .TP
112 \fB--cd-and-readdir\fP
113 Step in the directory of the first file to be loaded, push other files from that directory, and jump back to the first file.
114 Useful when invoking from a desktop environment.
115 .TP
116 \fB-c \fR\fI{commands}\fR\fP, \fB--execute-commands \fR\fI{commands}\fR\fP
117 Execute \fR\fI{commands}\fR after reading the initialization file, just before entering the interactive mode.
118 No semicolon (\fB;\fP) is required at the end of \fR\fI{commands}\fR.
119 Do not forget quoting \fR\fI{commands}\fR in a manner suitable to your shell.
120 So -c next is fine as it is.
121 A more complicated example, with quotings:
122 -c '*2;2pan_up;display;while(1){align "bottom";sleep "1" ; align "top"}'
123 (with the single quotes) tells fim to: double the displayed image
124 size, pan twice up, display the image, and finally
125 do an endless loop consisting of bottom and top aligning, alternated.
126
127 .TP
128 \fB-C \fR\fI{commands}\fR\fP, \fB--execute-commands-early \fR\fI{commands}\fR\fP
129 Similar to the \fB--execute-commands\fP option, but execute \fR\fI{commands}\fR earlier, just before reading the initialization file.
130 If \fR\fI{commands}\fR takes the special 'early' form \fR\fI=var=val\fR, it assigns value \fR\fIval\fR to variable \fR\fIvar\fR immediately, before the interpreter is started, and with no value quoting needed.
131
132 For example,
133 -C '\fB_scale_style\fP=" "' starts fim no auto-scaling;
134 the equivalent early form is:
135 -C '=\fB_scale_style\fP= '.
136
137
138 .TP
139 \fB-d \fR\fI{fbdev}\fR\fP, \fB--device \fR\fI{fbdev}\fR\fP
140 Framebuffer device to use. Default is the one your vc is mapped to (as in fbi).
141 .TP
142 \fB--dump-reference-help[=man]\fP
143 Dump to stdout language reference help and quit.
144 .TP
145 \fB--dump-default-fimrc\fP
146 Dump default configuration (the one hardcoded in the fim executable) to standard output and quit.
147 .TP
148 \fB-E \fR\fI{scriptfile}\fR\fP, \fB--execute-script \fR\fI{scriptfile}\fR\fP
149 Execute \fR\fI{scriptfile}\fR after the default initialization file is read, and before executing \fB--execute-commands\fP commands.
150 .TP
151 \fB-f \fR\fI{fimrc}\fR\fP, \fB--etc-fimrc \fR\fI{fimrc}\fR\fP
152 Specify an alternative system-wide initialization file (default: @sysconfdir@/fimrc), to be read prior to any other configuration file. See also \fB--no-etc-fimrc-file\fP.
153
154 .TP
155 \fB-F \fR\fI{commands}\fR\fP, \fB--final-commands \fR\fI{commands}\fR\fP
156 Similar to the \fB--execute-commands\fP option, but execute \fR\fI{commands}\fR after exiting the interactive mode, just before terminating the program.
157 .TP
158 \fB-h[s|d|l|m]\fP, \fB--help[=s|d|l|m]\fP
159 Print program invocation help, and exit. Depending on the option, output can be: short, descriptive, long from man, or complete man. For each further argument \fR\fI{help-item}\fR passed to \fBfim\fP, an individual help message is shown. If \fR\fI{help-item}\fR starts with a /, it is treated as a search string (not a regexp, though).
160 .TP
161 \fB-k \fR\fI{keysym}\fR\fP, \fB--keysym-press \fR\fI{keysym}\fR\fP
162 Execute any command bound (via the bind command) to a specified keysym at startup. A keysym can be prefixed by a repetition count number. You can specify the option multiple times to simulate multiple keystrokes. Presses entered via \fB--keysym-press\fP are processed with the same priority as those entered via \fB--chars-press\fP, that is, as they appear. See man \fR\fIfimrc\fR(5) for a list of keysyms and the use of bind.
163 .TP
164 \fB-K \fR\fI{chars}\fR\fP, \fB--chars-press \fR\fI{chars}\fR\fP
165 Input one or more keyboard characters at program startup (simulate keyboard presses). This option can be specified multiple times. Each additional time (or if the string is empty), a press of Enter (ASCII code 0x0D) key is prepended. Examples: -K '' simulates press of an Enter; -K ':next;' activates the command line and enter "next;" without executing it; -K ":next;" -K "next" executes "next", stays in the command line and enter keys "next"; -K ":next;" -K "" -K "next" executes "next", leaves the command line, and executes in sequence any command bound to keys 'n', 'e', 'x', 't'. Presses entered via \fB--chars-press\fP are processed with the same priority as those entered via \fB--keysym-press\fP, that is, as they appear.
166 .TP
167 \fB-D \fR\fI{filename}\fR\fP, \fB--load-image-descriptions-file \fR\fI{filename}\fR\fP
168 Load image descriptions from file \fR\fI{filename}\fR. Each line begins with the basename of an image file, followed by a Tab character (or a different character if specified via \fB--image-descriptions-file-separator\fP), then the description text. The description text is copied into the \fBi:_comment\fP variable of the image at load time, overriding the comment possibly loaded from the file (e.g. JPEG, PNG or TIFF comment). If a '@' followed by an identifier \fR\fI{identifier}\fR is encountered, and i:\fR\fI{var}\fR is set, its value is substituted here. If "@#" is encountered, the remainder of the description line is ignored. Special comment lines like "#!fim:\fR\fI{var}\fR=\fR\fI{val}\fR" lead i:\fR\fI{var}\fR to be assigned value \fR\fI{val}\fR (unquoted) at image loading time (cached variable), unless \fR\fI{var}\fR starts with an underscore ('_'). Special comment lines like "#!fim:@\fR\fI{var}\fR=\fR\fI{val}\fR" create a variable \fR\fI{var}\fR that are only valid in expanding @\fR\fI{var}\fR in comments. Special comment lines like "#!fim:\fR\fI{var}\fR@=\fR\fI{val}\fR" or "#!fim:@\fR\fI{var}\fR@=\fR\fI{val}\fR (notice @ before =) also expand whatever @\fR\fI{identifier}\fR encountered in \fR\fI{val}\fR . Special comment lines like "#!fim:+=\fR\fI{val}\fR" add \fR\fI{val}\fR to current description. Special comment lines like "#!fim:^=\fR\fI{val}\fR" set \fR\fI{val}\fR to be the base of each description. Special comment lines like "#!fim:!=" reset all cached variables. Special comment lines like "#!fim:/=\fR\fI{dir}\fR" prepend \fR\fI{dir}\fR to each file's basename. Special comment lines like "#!fim:\e=\fR\fI{dir}\fR" prepend \fR\fI{dir}\fR to each file's name. Special description text (to be associated to an image) begins with markers: with "#!fim:=", the last description line is reused; with "#!fim:+", what follows is appended to the last description line; with "#!fim:^", what follows is prepended to the last description line; with "#!fim:s/\fR\fI{f}\fR/\fR\fI{t}\fR", the last description line is used and substituted substring \fR\fI{t}\fR to occurrences of substring \fR\fI{f}\fR (\fR\fI{f}\fR and \fR\fI{t}\fR cannot contain newlines or a '/'). If \fR\fI{val}\fR is empty that variable is unset. These variables are stored also in an internal index used by the limit command. This option sets \fB_caption_over_image\fP=2, so that a caption is displayed over the image. A description file beginning with "#!fim:desc" can be loaded without specifying this switch.
169 .TP
170 \fB-S \fR\fI{sepchar}\fR\fP, \fB--image-descriptions-file-separator \fR\fI{sepchar}\fR\fP
171 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.
172 .TP
173 \fB-i\fP, \fB--image-from-stdin\fP
174 Read one single image from the standard input (the image data, not the filename). May not work with all supported file formats.
175 In the image list, this image takes the special name "<STDIN>".
176
177 .TP
178 \fB--mark-from-image-descriptions-file \fR\fI{filename}\fR\fP
179 Set those files specified in \fR\fI{filename}\fR (see --load-image-descriptions-file for the file format) as marked (see the list command).
180
181 .TP
182 \fB-m \fR\fI{vmode}\fR\fP, \fB--mode \fR\fI{vmode}\fR\fP
183 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.
184 .TP
185 \fB-N\fP, \fB--no-rc-file\fP
186 No personal initialization file is read (default is ~/.fimrc) at startup.
187 .TP
188 \fB--no-etc-fimrc-file\fP
189 No system-wide initialization file is read (default is @sysconfdir@/fimrc) at startup. See also \fB--etc-fimrc\fP.
190
191 .TP
192 \fB--no-internal-config\fP
193 No internal default configuration at startup (uses internal variable \fB_no_default_configuration\fP). Will only provide a minimal working configuration.
194 .TP
195 \fB--no-commandline\fP
196 With internal command line mode disabled.
197 .TP
198 \fB--no-history-save\fP
199 Do not save execution history at finalization (uses internal variable \fB_save_fim_history\fP).
200 .TP
201 \fB--no-history-load\fP
202 Do not load execution history at startup.
203 .TP
204 \fB--no-history\fP
205 Do not load or save execution history at startup.
206 .TP
207 \fB-p\fP, \fB--script-from-stdin\fP
208 Read commands from stdin before entering in interactive mode.
209 .TP
210 \fB-o [fb|sdl|gtk|ca|aa|dumb][=\fR\fI{gfxopts}\fR]\fP, \fB--output-device [fb|sdl|gtk|ca|aa|dumb][=\fR\fI{gfxopts}\fR]\fP
211 Use the specified \fBdevice\fP (one among fb|sdl|gtk|ca|aa|dumb) as fim video output device, overriding automatic checks.
212 If the \fBdevice\fP is empty and followed by \fR\fI{gfxopts}\fR, it will be selected automatically.
213 The available devices depend on the current environment and on the configuration and compilation options.
214 You can get the list of available output devices issuing \fBfim --version\fP.
215 The possible values to \fR\fI{gfxopts}\fR that we describe here can also be passed as "display 'reinit' \fR\fI{gfxopts}\fR" -- see man \fR\fIfimrc\fR for this.
216 The device name with options (perhaps with modifications due to auto-detection) is stored in variable \fB_device_string\fP.
217 The \fBfb\fP option selects the Linux framebuffer. Presence of \fR\fI{gfxopts}\fR with value \fB'S'\fP (e.g. '\fBfb=S\fP') makes framebuffer initialization more picky: it does not tolerate running in a screen session.
218 The \fBca\fP option (coloured ASCII-art) can be specified as \fBca\fP\fB[={['w']['h']['H']['d:'DITHERMODE]}] \fP; if supplied, \fB'w'\fP selects windowed mode, provided libcaca is running under X; by default (or with \fB'W'\fP), windowed mode is being turned off internally during initialization by unsetting the DISPLAY environment variable. If \fB'd:'\fP is present, the \fBDITHERMODE\fP following it will be passed as dither algorithm string (alternatively, it can be a non-negative number, too).
219 The \fBaa\fP (monochrome ASCII-art) option can be specified as \fBaa[={['w'|'W']}]\fP; if supplied, \fB'w'\fP selects windowed mode, provided aalib is running under X; by default (or with \fB'W'\fP), windowed mode is being turned off internally during initialization by unsetting the DISPLAY environment variable.
220 Please note that the readline (internal command line) functionality in \fBca\fP and \fBaa\fP modes is limited.
221 If the graphical windowed mode is \fBsdl\fP or \fBgtk\fP it can be followed by \fB \:={['w']['m']['r']['h']['W']['M']['R']['H'][width[:height]]['%']}\fP, where \fBwidth\fP and \fBheight\fP are integer numbers specifying the desired resolution (if \fBheight\fP not specified, it takes the value of \fBwidth\fP); the \fB'w'\fP character requests windowed mode (instead of \fB'W'\fP for fullscreen); the \fB'm'\fP character requests mouse pointer display; the \fB'h'\fP character requests help grid map draw (can be repeated for variants); the \fB'r'\fP character requests support for window resize; the \fB'%'\fP character requests to treat \fBwidth\fP and \fBheight\fP as percentage of possible window resolution. The same letters uppercase request explicit negation of the mentioned features.
222 Additionally, in \fBgtk\fP mode: \fB'b'\fP hides the menu bar, \fB'e'\fP starts with empty menus, \fB'f'\fP rebuilds the menus, and \fB'D'\fP removes the menus. \fBNote\fP: the \fBgtk\fP mode is a recent addition and may have defects. The \fBsdl\fP mode works best with libsdl-2; libsdl-1.2 support is being discontinued.
223 The \fBimlib2\fP option requests imlib2 and is unfinished: do not use it.
224 The \fBdumb\fP test mode is there only for test purposes and is not interactive.
225
226 .TP
227 \fB--offset \fR\fI{bytes-offset[{:upper-offset}|{+offset-range}]}\fR\fP
228 Use the specified \fR\fIoffset\fR (in bytes) for opening the specified files. If \fR\fI:upper-offset\fR is specified, further bytes until \fR\fIupper-offset\fR are probed. If \fR\fI+offset-range\fR is specified instead, that many additional bytes are to be probed. Use this option to search damaged file systems for image files. Appending a modifier among 'K','M','G' (case irrelevant) to an offset number changes the unit to be respectively 2^10, 2^20, or 2^30 bytes.
229 .TP
230 \fB--pread-cmd \fR\fI{cmd-filter-pipeline}\fR\fP
231 Specify a shell command with \fR\fI{cmd-filter-pipeline}\fR. If the current filename matches "^[/A-Za-z0-9_.][/A-Za-z0-9_.-]*$", it is be substituted to any occurrence of '{}'. The resulting command output is assumed to be file data, which is read, decoded, and displayed.
232 This works by setting the internal \fB_pread_cmd\fP variable (empty by default).
233 .TP
234 \fB-P\fP, \fB--text-reading\fP
235 Enable textreading mode. This has the effect that fim displays images scaled to the width of the screen, and aligned to the top. If the images you are watching are 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).
236 .TP
237 \fB-s \fR\fI{value}\fR\fP, \fB--scroll \fR\fI{value}\fR\fP
238 Set scroll steps for internal variable \fB_steps\fP (default is "20%").
239 .TP
240 \fB--slideshow \fR\fI{number}\fR\fP
241 Interruptible slideshow mode. Wait for \fR\fI{number}\fR of seconds (can have a decimal part, and is assigned to the _slideshow_sleep_time variable) after each image. Implemented by executing reload; i:fresh=1; while(_fileindex <= _filelistlen-_loop_only_once){sleep _slideshow_sleep_time; next;} _loop_only_once=0; sleep _slideshow_sleep_time; as a first command. Can be interrupted by : or Esc. The other keys execute accordingly to their function but do not interrupt the slideshow. Like in fbi, this cycles forever, unless \fB--once\fP is specified.
242 .TP
243 \fB--sanity-check\fP
244 Perform a quick sanity check, just after the initialization, and terminate.
245 .TP
246 \fB-t\fP, \fB--no-framebuffer\fP
247 \fBfim\fP Use an ASCII Art driver. If present, use either of libcaca (coloured), or aalib (monochrome). For more, see (man fimrc), (info aalib) or (apropos caca)).
248 If no ASCII Art driver had been enabled at compile time, fim does not display any image at all.
249 .TP
250 \fB-T \fR\fI{terminal}\fR\fP, \fB--vt \fR\fI{terminal}\fR\fP
251 The \fR\fI{terminal}\fR is to be used as virtual terminal device file (as in fbi).
252 See (chvt (1)), (openvt (1)) for more info about this.
253 Use (con2fb (1)) to map a terminal to a framebuffer device.
254
255 .TP
256 \fB--reverse\fP
257 Reverse files list before browsing (can be combined with the other sorting options).
258 .TP
259 \fB--sort\fP
260 Sort files list before browsing according to full filename.
261 .TP
262 \fB--sort-basename\fP
263 Sort files list before browsing according to file basename's.
264 .TP
265 \fB--sort-mtime\fP
266 Sort files list before browsing according to file modification time.
267 .TP
268 \fB--sort-fsize\fP
269 Sort files list before browsing according to file size.
270 .TP
271 \fB-u\fP, \fB--random\fP
272 Randomly shuffle the files list before browsing (seed depending on time() function).
273 .TP
274 \fB--random-no-seed\fP
275 Pseudo-random shuffle the files list before browsing (no seeding).
276 .TP
277 \fB-v\fP, \fB--verbose\fP
278 Be verbose: show status bar.
279 .TP
280 \fB--verbose-load\fP
281 Load files verbosely (repeat option to increase verbosity).
282 .TP
283 \fB--verbose-font-load\fP
284 Load font verbosely (sets \fB_fbfont_verbosity\fP).
285 .TP
286 \fB--verbose-interpreter\fP
287 Execute interpreter verbosely (Sets immediately \fB_debug_commands\fP="ackCm" if specified once, \fB_debug_commands\fP="ackCmmi" if specified twice).
288 .TP
289 \fB-V\fP, \fB--version\fP
290 Print to stdout program version, compile flags, enabled features, linked libraries information, supported filetypes/file loaders, and then exit.
291 .TP
292 \fB-w\fP, \fB--autowidth\fP
293 Scale the image according to the screen width.
294 .TP
295 \fB-=\fP, \fB--no-auto-scale\fP
296 Do not scale the images after loading (sets '\fB_scale_style\fP=" "';).
297 .TP
298 \fB--autowindow\fP
299 Resize the window size (if supported by the video mode) to the image size. Don't use this with other image scaling options.
300 .TP
301 \fB--no-stat-push\fP
302 Sets \fB_push_checks\fP=0 before initialization, thus disabling file/dir existence checks with stat(2) at push push time (and speeding up startup).
303 .TP
304 \fB-H\fP, \fB--autoheight\fP
305 Scale the image according to the screen height.
306 .TP
307 \fB-W \fR\fI{scriptfile}\fR\fP, \fB--write-scriptout \fR\fI{scriptfile}\fR\fP
308 All the characters that you type are recorded in the file \fR\fI{scriptfile}\fR, until you exit \fBfim\fP. 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 \fR\fI{scriptfile}\fR file exists, it is not touched (as in Vim's -w).
309 .TP
310 \fB-L \fR\fI{fileslistfile}\fR\fP, \fB--read-from-file \fR\fI{fileslistfile}\fR\fP
311 Read file list from a file: each line one file to load (similar to \fB--read-from-stdin\fP; use \fB--read-from-stdin-elds\fP to control line breaking).
312
313
314 .TP
315 \fB -, \fP\fB--read-from-stdin\fP
316 Read file list from stdin: each line one file to load; use with --read-from-stdin-elds to control line breaking).
317
318 Note that these three standard input reading functionalities (-i,-p and -) conflict : if two or more of them occur in fim invocation, fim exits with an error and warn about the ambiguity.
319
320 See the section
321 .B INVOCATION EXAMPLES
322 below to read some useful (and unique) ways of employing fim.
323
324 .TP
325 \fB--read-from-stdin-elds \fR\fI{delimiter-char}\fR\fP
326 Specify an endline delimiter character for breaking lines read via -/--read-from-stdin/--read-from-file (which shall be specified after this). Line text before the delimiter are be treated as names of files to load; the text after is ignored. This is also useful e.g. to load description files (see --load-image-descriptions-file) as filename list files. Default is the newline character (0x0A); to specify an ASCII NUL byte (0x00) use ''.
327
328 .TP
329 \fB-A\fP, \fB--autotop\fP
330 Align images to the top border (by setting '\fB_autotop\fP=1' after initialization).
331 .TP
332 \fB-q\fP, \fB--quiet\fP
333 Quiet execution mode. Sets _display_status=0;_display_busy=0;.
334
335 .TP
336 \fB-r \fR\fI{{width:height}|'fullscreen'}\fR\fP, \fB--resolution \fR\fI{{width:height}|'fullscreen'}\fR\fP
337 Set resolution specification in pixels dimensions. Supported only by GTK and SDL. Will be appended to the argument to --output-device. Shorthand value 'fullscreen' is translated as 'W'.
338 .TP
339 \fB-R[\fR\fI{exp}\fR]\fP, \fB--recursive[=\fR\fI{exp}\fR]\fP
340 Push files/directories to the files list recursively. The expression in variable \fB_pushdir_re\fP (default: "\.(JPG|PNG|GIF|BMP|TIFF|TIF|JPEG|JFIF|PPM|PGM|PBM|PCX|QOI|AVIF|WEBP)$") lists extensions of filenames which are loaded in the list. You can overwrite its value by optionally passing an expression \fR\fI{exp}\fR here as argument. If starting with '+' or '|', the expression following is to be appended to it.
341 .TP
342 \fB-X\fP, \fB--no-pipe-load\fP
343 Do not load via external converter programs: only use built-in file decoders.
344 .TP
345 \fB-B\fP, \fB--background-recursive\fP
346 Push files/directories to the files list recursively, in background during program execution. Any sorting options are ignored. Experimental feature, unfinished.
347 .TP
348 \fB--load-shadow-directory \fR\fI{dirname}\fR\fP
349 Add \fR\fI{dirname}\fR to the shadow directory list. Then 'scale "shadow"' temporarily substitutes the image being displayed with that of the first same-named file located under a shadow directory. Useful to browse low-res images, but still being able to quickly view the hi-res original residing in a shadow directory. This works as intended as long as unique filenames are involved.
350 .TP
351 \fB-/ \fR\fI{pattern}\fR\fP, \fB--/ \fR\fI{pattern}\fR\fP
352 After startup jump to pattern; short for -c '/' \fR\fI{pattern}\fR.
353 .TP
354 \fB--// \fR\fI{pattern}\fR\fP
355 After startup jump to pattern; as -c '/'\fR\fI{pattern}\fR but with search on the full path (with \fB_re_search_opts="f"\fP).
356 .TP
357 \fB-1\fP, \fB--once\fP
358 If running --slideshow, loop only once (as in fbi).
359
360 .SH PROGRAM RETURN STATUS
361 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.
362 The return status may be controlled by the use of the quit command.
363 .SH COMMON KEYS AND COMMANDS
364 .nf
365 The following keys and commands are default hardcoded in the minimal configuration. These are working by default before any configuration file loading, and before the hardcoded config loading (see variable \fB_fim_default_config_file_contents\fP).
366
367 n goto '+1f'
368 p goto '-1f'
369 + scale '+'
370 - scale '-'
371 h pan 'left'
372 l pan 'right'
373 k pan 'up-'
374 j pan 'down+'
375 q quit
376 You can type a number before a command binding to iterate the assigned command:
377 3k 3pan 'up-'
378
379 .nf
380 : enter command line mode (here one can use readline bindings as C-r, C-s, M-b, M-f, ...)
381 :\fR\fI{number}\fR jump to \fR\fI{number}\fR^th image in the list
382 :^ jump to first image in the list
383 :$ jump to last image in the list
384 :*\fR\fI{factor}\fR scale the image by \fR\fI{factor}\fR
385 :\fR\fI{scale}\fR% scale the image to the desired \fR\fI{scale}\fR
386 :+\fR\fI{scale}\fR% scale the image up to the desired percentage \fR\fI{scale}\fR (relatively to the original)
387 :-\fR\fI{scale}\fR% scale the image down to the desired percentage \fR\fI{scale}\fR (relatively to the original)
388
389 /\fR\fI{regexp}\fR entering the pattern \fR\fI{regexp}\fR (with '/') makes fim jump to the next image whose filename matches \fR\fI{regexp}\fR
390 /*.png$ entering this pattern (with '/') makes fim jump to the next image whose filename ends with 'png'
391 /png a shortcut for '/.*png.*'
392
393 2,4 stdout '{}' print three filenames to standard output.
394
395
396 !\fR\fI{syscmd}\fR executes the \fR\fI{syscmd}\fR quoted string as an argument to the "system" fim command.
397
398
399 You can visualize all of the default bindings invoking fim --dump-default-fimrc | grep bind .
400 You can visualize all of the default aliases invoking fim --dump-default-fimrc | grep alias .
401
402 .fi
403 .P
404 The Return vs. Space key thing can be used to create a file list while
405 reviewing the images and use the list for batch processing later on.
406
407 All of the key bindings are reconfigurable; see the default
408 .B fimrc
409 file for examples on this, or read the complete manual: the FIM.TXT file
410 distributed with fim.
411 .SH AFFECTING ENVIRONMENT VARIABLES
412 .nf
413 FBFONT (just like in fbi) a Linux consolefont font file.
414 If using a gzipped font file, the zcat program is used to uncompress it (via \fBexecvp(3)\fP).
415 If FBFONT is unset, the following files are probed and the first existing one is selected:
416
417 @FIM_CUSTOM_DEFAULT_CONSOLEFONT@
418 /usr/share/kbd/consolefonts/cp866-8x16.psf.gz
419 /usr/share/consolefonts/Uni3-TerminusBoldVGA14.psf.gz
420 /usr/lib/kbd/consolefonts/lat9-16.psf.gz
421 /usr/share/consolefonts/lat1-16.psf
422 /usr/share/consolefonts/lat1-16.psf.gz
423 /usr/share/consolefonts/lat1-16.psfu.gz
424 /usr/share/kbd/consolefonts/lat1-16.psf
425 /usr/share/kbd/consolefonts/lat1-16.psf.gz
426 /usr/share/kbd/consolefonts/lat1-16.psfu.gz
427 /usr/lib/kbd/consolefonts/lat1-16.psf
428 /usr/lib/kbd/consolefonts/lat1-16.psf.gz
429 /usr/lib/kbd/consolefonts/lat1-16.psfu.gz
430 /lib/kbd/consolefonts/lat1-16.psf
431 /lib/kbd/consolefonts/lat1-16.psf.gz
432 /lib/kbd/consolefonts/lat1-16.psfu.gz
433 /lib/kbd/consolefonts/Lat2-VGA14.psf.gz
434 /lib/kbd/consolefonts/Lat2-VGA16.psf.gz
435 /lib/kbd/consolefonts/Lat2-VGA8.psf.gz
436 /lib/kbd/consolefonts/Uni2-VGA16.psf.gz
437 /usr/share/consolefonts/default8x16.psf.gz
438 /usr/share/consolefonts/default8x9.psf.gz
439 /usr/share/consolefonts/Lat15-Fixed16.psf.gz
440 /usr/share/consolefonts/default.psf.gz
441 fim://
442
443 If the special fim:// string is specified, a hardcoded font is used.
444 FBGAMMA (just like in fbi) gamma correction (applies to dithered 8 bit mode only). Default is 1.0.
445 FRAMEBUFFER (just like in fbi) user set framebuffer device file (applies only to the fb mode).
446 If unset, fim probes for /dev/fb0.
447 TERM (only in fim) influences the output device selection algorithm, especially if $TERM=="screen".
448 SSH_TTY if set and no output device specified, assume we're over \fBssh\fP, and give precedence to ca, then aa (if present).
449 TERMUX_VERSION if set and no output device specified, assume we're over \fBtermux\fP, and give precedence to ca, then aa (if present).
450 WAYLAND_DISPLAY if set and no output device specified, assume we're over \fBWayland\fP, and give precedence to gtk, then sdl, then ca, then aa (if present).
451 DISPLAY If this variable is set, then the gtk driver has precedence, then sdl.
452 .SH COMMON PROBLEMS
453 .B fim -o fb
454 needs read-write access to the framebuffer devices (/dev/fbN or /dev/fb/N), i.e you (our
455 your admin) have to make sure fim can open the devices in rw mode.
456 The IMHO most elegant way is to use pam_console (see
457 /etc/security/console.perms) to chown the devices to the user logged
458 in on the console. Another way is to create some group, chown the
459 special files to that group and put the users which are allowed to use
460 the framebuffer device into the group. You can also make the special
461 files world writable, but be aware of the security implications this
462 has. On a private box it might be fine to handle it this way
463 through.
464
465 If using udev, you can edit:
466 /etc/udev/permissions.d/50-udev.permissions
467 and set these lines like here:
468 # fb devices
469 fb:root:root:0600
470 fb[0-9]*:root:root:0600
471 fb/*:root:root:0600
472 .P
473
474 .B fim -o fb
475 also needs access to the linux console (i.e. /dev/ttyN) for sane
476 console switch handling. That is obviously no problem for console
477 logins, but any kind of pseudo tty (xterm, ssh, screen, ...) will
478 .B not
479 work.
480 .SH INVOCATION EXAMPLES
481 .B fim --help -R -B
482 .fi
483 # get help for options \fB-R\fP and
484 .B -B
485 .P
486 .P
487
488 .B fim media/
489 .fi
490 # load files from the directory
491 .B media/
492 .P
493 .P
494
495 .B fim -R media/ --sort
496 .fi
497 # open files found by recursive traversal of directory media, then sorting the list
498 .P
499 .P
500
501 .B find /mnt/media/ -name *.jpg | fim -
502 .fi
503 # read input files list from standard input
504 .P
505 .P
506
507 .B find /mnt/media/ -name *.jpg | shuf | fim -
508 .fi
509 # read input files list from standard input, randomly shuffled
510 .P
511 .P
512
513 .B cat script.fim | fim -p images/*
514 .fi
515 # read a script file
516 .B script.fim
517 from standard input before displaying files in the directory
518 .B images
519 .P
520 .P
521
522 .B scanimage ... | tee scan.ppm | fim -i
523 .fi
524 # read the image scanned from a flatbed scanner as soon as it is read
525 .P
526 .P
527
528 .B h5topng -x 1 -y 2 dataset.hdf -o /dev/stdout | fim -i
529 .fi
530 # visualize a slice from an HDF5 dataset file
531 .P
532 .P
533
534 .B fim * > selection.txt
535 .fi
536 # output the file names marked interactively with the 'list "mark"' command in fim to a file
537 .P
538 .P
539
540 .B fim * | fim -
541 .fi
542 # output the file names marked with 'm' in fim to a second instance of fim, in which these could be marked again
543 .P
544 .P
545
546 .B fim
547 -c 'pread "vgrabbj -d /dev/video0 -o png";reload'
548 .fi
549 # display an image grabbed from a webcam
550 .P
551 .P
552
553 .B fim
554 -o aa -c 'pread "vgrabbj -d /dev/video0 -o png";reload;system "fbgrab" "asciime.png"'
555 .fi
556 .fi
557 # if running in framebuffer mode, saves a png screenshot with an ASCII rendering of an image grabbed from a webcam
558 .P
559 .P
560
561 .B fim
562 -c 'while(1){pread "vgrabbj -d /dev/video0 -o png";reload;sleep 1;};'
563
564 .fi
565 # display a sequence of images grabbed from a webcam; circa 1 per second
566 .P
567 .P
568
569 .SH NOTES
570 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.
571 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.
572 .SH BUGS
573 \fBfim\fP has bugs. Please read the
574 .B BUGS
575 file shipped in the documentation directory to discover the known ones.
576 There are also inconsistencies in the way the internal command line works across the different graphical devices.
577 .SH FILES
578
579 .TP 15
580 .B @docdir@
581 The directory with \fBfim\fP documentation files.
582 .TP 15
583 .B @sysconfdir@/fimrc
584 The system-wide \fBfim\fP initialization file (executed at startup, after executing the hardcoded configuration).
585 .TP 15
586 .B ~/.fimrc
587 The personal \fBfim\fP initialization file (executed at startup, after the system-wide initialization file).
588 .TP 15
589 .B ~/.fim_history
590 File where to load from or save command history. See (man \fR\fIfimrc\fR(5), man \fR\fIreadline\fR(3)).
591 .TP 15
592 .B ~/.inputrc
593 If \fBfim\fP is built with GNU readline support, it is susceptible to changes in the user set ~/.inputrc configuration file contents. For details, see (man \fR\fIreadline\fR(3)).
594 .SH SEE ALSO
595 Other \fBfim\fP man pages: \fR\fIfimgs\fR(1), \fR\fIfimrc\fR(1).
596 .fi
597 Conversion programs: \fR\fIconvert\fR(1), \fR\fIdia\fR(1), \fR\fIxcftopnm\fR(1), \fR\fIfig2dev\fR(1), \fR\fIinkscape\fR(1).
598 .fi
599 Related programs: \fR\fIfbset\fR(1), \fR\fIcon2fb\fR(1), \fR\fIvim\fR(1), \fR\fImutt\fR(1), \fR\fIexiftool\fR(1), \fR\fIexiftags\fR(1), \fR\fIexiftime\fR(1), \fR\fIexifcom\fR(1), \fR\fIfbi\fR(1), \fR\fIfbida\fR(1), \fR\fIfeh\fR(1), \fR\fIqiv\fR(1), \fR\fIsxiv\fR(1), \fR\fIfbgrab\fR(1).
600 .fi
601 Related documentation: \fR\fIfbdev\fR(4), \fR\fIvcs\fR(4), \fR\fIfb.modes\fR(8), \fR\fIfbset\fR(8), \fR\fIsetfont\fR(8).
602 .fi
603 .SH AUTHOR
604 .nf
605 Michele Martone <dezperado _CUT_ autistici _CUT_ org> is the author of fim, "Fbi IMproved".
606 .fi
607 .SH COPYRIGHT
608 .nf
609 Copyright (C) 2007-2024 Michele Martone <dezperado _CUT_ autistici _CUT_ org> (author of fim)
610 .fi
611 Copyright (C) 1999-2004 Gerd Hoffmann <kraxel _CUT_ bytesex.org> is the author of "fbi", upon which
612 .B fim
613 was originally based.
614 .P
615 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.
616 .P
617 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.
618 .P
619 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.
620