1 .\" -*- coding: us-ascii -*-
4 conky \- a system monitor for X originally based on the torsmo code, but more kickass.
8 .if (\nxu > (\n(.lu / 2)) .nr x (\n(.lu / 5)
14 Conky is a system monitor for X originally based on the torsmo code.
15 Since it's original conception, Conky has changed a fair bit from it's predecessor.
16 Conky can display just about anything, either on your root desktop or in it's own window.
17 Conky has many built-in objects, as well as the ability to execute programs and scripts,
18 then display the output from stdout.
20 We are always looking for help, and anyone interested in becoming a developer is welcome.
21 Please use the facilities at SourceForge to make bug reports, feature requests, and submit patches.
23 Thanks for your interest in Conky.
25 To compile and run Conky with all optional components (If you run Gentoo, see the "Ebuild" Section below):
27 \fBsh autogen.sh\fR \fB# Only required if building from CVS\fR
29 \fB\&./configure \fR\fB\-\-prefix=/usr \-\-mandir=/usr/share/man \-\-infodir=/usr/share/info \-\-datadir=/usr/ share \-\-sysconfdir=/etc \-\-localstatedir=/var/lib \-\-enable\-double\-buffer \-\-enable\-own\-window \-\-enable\-proc\-uptime \-\-enable\-mpd \-\-enable\-xft \-\-enable\-seti\fR
35 Conky doesn't probably compile with other compilers than gcc and icc.
36 It doesn't compile with C89 compiler and not even with pure C99.
37 It uses few things that might not exist: strdup(), strcasecmp(), strncasecmp(),
38 optarg variable with getopt() and long long (not in C89). Crashes in file system
39 statistics stuff when compiled with icc, I don't know exactly why.
41 You can disable 'drawing to own window' feature in case you don't need it by passing
42 --disable-own-window to configure -script.
44 Conky is in Gentoo's Portage. Simply use "emerge conky" to install conky.
45 There is also usually an up-to-date ebuild within Conky's package or in CVS.
47 Conky is generally very good on resources. However, certain objects in
48 Conky are harder on resources then others. In particular, the $tail,
49 $top, $font, and $graph objects are quite costly in comparison to the rest of Conky.
51 If you do use them, please do not complain about memory or CPU usage,
52 unless you think something is going seriously wrong (mem leak, et cetera).
54 Command line options override configurations defined in configuration file.
57 Prints version and exits
60 \fB\-a \fR\fBALIGNMENT\fR
61 Text alignment on screen, {top,bottom}_{left,right} or none
65 Use double buffering (eliminates flicker)
69 Config file to load instead of $HOME/.conkyrc
73 Daemonize, fork to background
81 Prints command line help and exits
85 Create own window to draw
89 Text to render, remember single quotes, like -t ' $uptime '
92 \fB\-u \fR\fBSECONDS\fR
96 \fB\-w \fR\fBWIN_ID\fR
100 \fB\-x \fR\fBX_COORDINATE\fR
104 \fB\-y \fR\fBY_COORDINATE\fR
107 .SH "CONFIGURATION SETTINGS"
108 Default configuration file is $HOME/.conkyrc (can be changed from
109 conky.c among other things). See conkyrc.sample. You might want to copy
110 it to $HOME/.conkyrc and then start modifying it.
113 Aligned position on screen, may be top_left, top_right, bottom_left, bottom_right, or none
117 Boolean value, if true, Conky will be forked to background when started
121 Set conky on the bottom of all other applications
125 Border margin in pixels
129 Border width in pixels
132 \fBcpu_avg_samples\fR
133 The number of samples to average for CPU monitoring
137 Default color and border color
140 \fBdefault_shade_color\fR
141 Default shading color and border's shading color
144 \fBdefault_outline_color\fR
145 Default outline color
149 Use the Xdbe extension? (eliminates flicker) It is highly recommended to use own window with this one so double buffer won't be so big.
153 Draw borders around text?
165 Font name in X, xfontsel can be used to get a nice font
169 Gap between right or left border of screen, same as passing -x at command line
173 Gap between top or bottom border of screen, same as passing -y at command line
177 Substract (file system) buffers from used memory?
181 Mail spool for mail checking
185 Minimum size of window
188 \fBmldonkey_hostname\fR
189 Hostname for mldonkey stuff, defaults to localhost
193 Mldonkey port, 4001 default
197 Mldonkey login, default none
200 \fBmldonkey_password\fR
201 Mldonkey password, default none
216 \fBnet_avg_samples\fR
217 The number of samples to average for net data
220 \fBoverride_utf8_locale\fR
221 Force UTF8? requires XFT
225 Boolean, create own window to draw?
229 Pad percentages to this many decimals (0 = no padding)
232 \fBstippled_borders\fR
233 Border stippling (dashing) in pixels
236 \fBtotal_run_times\fR
237 Total number of times for Conky to update before quitting. Zero makes Conky run forever
240 \fBupdate_interval\fR
241 Update interval in seconds
245 Boolean value, if true, text is rendered in upper case
249 Adds spaces after certain objects to stop them from moving other things around. Note that this only helps if you are using a mono font, such as Bitstream Vera Sans Mono.
253 Use Xft (anti-aliased font and stuff)
257 After this begins text to be formatted on screen
260 Colors are parsed using XParsecolor(), there might be a list of them:
261 /usr/X11R6/lib/X11/rgb.txt. Also,
262 http://sedition.com/perl/rgb.html [http://sedition.com/perl/rgb.html]
263 Color can be also in #rrggbb format (hex).
264 Note that when displaying bytes, power is 1024 and not 1000 so 1M really
265 means 1024*1024 bytes and not 1000*1000.
267 \fBaddr\fR \fB(interface)\fR
268 IP address for an interface
272 ACPI ac adapter state.
280 ACPI temperature in C.
284 ACPI temperature in F.
288 CPU temperature from therm_adt746x
292 Fan speed from therm_adt746x
295 \fBalignr\fR \fB(num)\fR
296 Right-justify text, with space of N
299 \fBalignc\fR \fB(num)\fR
303 \fBbattery\fR \fB(num)\fR
304 Remaining capacity in ACPI or APM battery. ACPI battery number can be given as argument (default is BAT0).
308 Amount of memory buffered
312 Amount of memory cached
315 \fBcolor\fR \fB(color)\fR
316 Change drawing color to color
320 CPU usage in percents
323 \fBcpubar\fR \fB(height),(width)\fR
324 Bar that shows CPU usage, height is bar's height in pixels
327 \fBcpugraph\fR \fB(height),(width) (gradient colour 1) (gradient colour 2)\fR
328 CPU usage graph, with optional colours in hex, minus the #.
331 \fBdownspeed\fR \fBnet\fR
332 Download speed in kilobytes
335 \fBdownspeedf\fR \fBnet\fR
336 Download speed in kilobytes with one decimal
339 \fBdownspeedgraph\fR \fBnet, (height),(width) (gradient colour 1) (gradient colour 2)\fR
340 Download speed graph, colours defined in hex, minus the #.
344 Text to show if any of the above are not true
347 \fBexec\fR \fBshell command\fR
348 Executes a shell command and displays the output in conky. warning: this takes a lot more resources than other variables. I'd recommend coding wanted behaviour in C and posting a patch.
351 \fBexecbar\fR \fBshell command\fR
352 Same as exec, except if the first value return is a value between 0-100, it will use that number for a bar. The size for the bar is currently fixed, but that may change in the future.
355 \fBexecgraph\fR \fBshell command\fR
356 Same as execbar, but graphs values
359 \fBexeci\fR \fBinterval, shell command\fR
360 Same as exec but with specific interval. Interval can't be less than update_interval in configuration.
363 \fBfont\fR \fBfont\fR
364 Specify a different font. Only applies to one line.
368 Returns CPU frequency in MHz
372 Returns CPU frequency in GHz
375 \fBfs_bar\fR \fB(height),(width) fs\fR
376 Bar that shows how much space is used on a file system. height is the height in pixels. fs is any file on that file system.
379 \fBfs_free\fR \fB(fs)\fR
380 Free space on a file system available for users.
383 \fBfs_free_perc\fR \fB(fs)\fR
384 Free percentage of space on a file system available for users.
387 \fBfs_size\fR \fB(fs)\fR
391 \fBfs_used\fR \fB(fs)\fR
392 File system used space
395 \fBhr\fR \fB(height)\fR
396 Horizontal line, height is the height in pixels
399 \fBi2c\fR \fB(dev), type, n\fR
400 I2C sensor from sysfs (Linux 2.6). dev may be omitted if you have only one I2C device. type is either in (or vol) meaning voltage, fan meaning fan or temp/tempf (first in C, second in F) meaning temperature. n is number of the sensor. See /sys/bus/i2c/devices/ on your local computer.
403 \fBif_running\fR \fB(process)\fR
404 if PROCESS is running, display everything if_running and the matching $endif
407 \fBif_existing\fR \fB(file)\fR
408 if FILE exists, display everything between if_existing and the matching $endif
411 \fBif_mounted\fR \fB(mountpoint)\fR
412 if MOUNTPOINT is mounted, display everything between if_mounted and the matching $endif
419 \fBlinkstatus\fR \fB(interface)\fR
420 Get the link status for wireless connections
424 (1,2,3)> System load average, 1 is for past 1 minute, 2 for past 5 minutes and 3 for past 15 minutes.
428 Machine, i686 for example
432 Mail count in mail spool. You can use program like fetchmail to get mails from some server using your favourite protocol. See also new_mails.
436 Amount of memory in use
439 \fBmembar\fR \fB(height),(width)\fR
440 Bar that shows amount of memory in use
444 Total amount of memory
448 Percentage of memory in use
451 \fBml_upload_counter\fR
452 total session upload in mb
455 \fBml_download_counter\fR
456 total session download in mb
459 \fBml_nshared_files\fR
460 number of shared files
463 \fBml_shared_counter\fR
464 total session shared in mb, buggy in some mldonkey versions
467 \fBml_tcp_upload_rate\fR
468 tcp upload rate in kb/s
471 \fBml_tcp_download_rate\fR
472 tcp download rate in kb/s
475 \fBml_udp_upload_rate\fR
476 udp upload rate in kb/s
479 \fBml_udp_download_rate\fR
480 udp download rate in kb/s
483 \fBml_ndownloaded_files\fR
484 number of completed files
487 \fBml_ndownloading_files\fR
488 number of downloading files
492 Artist in current MPD song must be enabled at compile
496 Album in current MPD song
499 \fBmpd_bar\fR \fB(height),(width)\fR
500 Bar of mpd's progress
504 Bitrate of current song
508 Playing, stopped, et cetera.
512 Title of current MPD song
528 Percent of song's progress
532 Unread mail count in mail spool.
539 \fBoutlinecolor\fR \fB(color)\fR
543 \fBpre_exec\fR \fBshell command\fR
544 Executes a shell command one time before conky displays anything and puts output as text.
548 Total processes (sleeping and running)
551 \fBrunning_processes\fR
552 Running processes (not sleeping), requires Linux 2.6
555 \fBshadecolor\fR \fB(color)\fR
559 \fBstippled_hr\fR \fB(space)\fR
560 Stippled (dashed) horizontal line
563 \fBswapbar\fR \fB(height),(width)\fR
564 Bar that shows amount of swap in use
568 Amount of swap in use
576 Percentage of swap in use
580 System name, Linux for example
583 \fBoffset\fR \fB(pixels)\fR
584 Move text over by N pixels. See also $voffset.
588 logfile, lines interval> Displays last N lines of supplied text text file. If interval is not supplied, Conky assumes 2x Conky's interval. Max of 30 lines. Max of 30 lines can be displayed.
591 \fBtime\fR \fB(format)\fR
592 Local time, see man strftime to get more information about format
595 \fBtotaldown\fR \fBnet\fR
596 Total download, overflows at 4 GB on Linux with 32-bit arch and there doesn't seem to be a way to know how many times it has already done that before conky has started.
599 \fBtop\fR \fBtype, num\fR
600 This takes arguments in the form:top (name) (number) Basically, processes are ranked from highest to lowest in terms of cpu usage, which is what (num) represents. The types are: "name", "pid", "cpu", and mem". There can be a max of 10 processes listed.
603 \fBtop_mem\fR \fBtype, num\fR
604 Same as top, except sorted by mem usage instead of cpu
607 \fBtotalup\fR \fBnet\fR
608 Total upload, this one too, may overflow
611 \fBupdates\fR \fBNumber of updates\fR
615 \fBupspeed\fR \fBnet\fR
616 Upload speed in kilobytes
619 \fBupspeedf\fR \fBnet\fR
620 Upload speed in kilobytes with one decimal
623 \fBupspeedgraph\fR \fBnet, (height),(width) (gradient colour 1) (gradient colour 2)\fR
624 Upload speed graph, colours defined in hex, minus the #.
632 Uptime in a shorter format
636 Seti@home current progress
639 \fBseti_progbar\fR \fB(height),(width)\fR
640 Seti@home current progress bar
644 Seti@home total user credit
647 \fBvoffset\fR \fB(pixels)\fR
648 Change verticle offset by N pixels. Negative values will cause text to overlap. See also $offset.
652 conky \fB\-t '${time %D %H:%m}' \-o \-u 30\fR
653 Start Conky in its own window with date and clock as text and 30 sec update interval.
655 conky \fB\-a top_left \-x 5 \-y 500 \-d\fR
656 Start Conky to background at coordinates (5, 500).
658 \fB~/.conkyrc\fR default configuration file
660 Drawing to root or some other desktop window directly doesn't work with
661 all window managers. Especially doesn't work well with Gnome and it has
662 been reported that it doesn't work with KDE either. Nautilus can be
663 disabled from drawing to desktop with program gconf-editor. Uncheck
664 show_desktop in /apps/nautilus/preferences/. There is -w switch in Conky
665 to set some specific window id. You might find xwininfo -tree useful to
666 find the window to draw to. You can also use -o argument which makes
667 Conky to create its own window.
669 http://conky.sourceforge.net [http://conky.sourceforge.net]
671 http://www.sourceforge.net/projects/conky [http://www.sourceforge.net/projects/conky]
673 #conky on irc.freenode.net
675 The Conky dev team. What's up now??!