6 conky - A system monitor for X originally based on the torsmo code, but
7 more kickass. It just keeps on given'er. Yeah.
13 Conky is a system monitor for X originally based on torsmo. Since its
14 inception, Conky has changed significantly from its predecessor, while
15 maintaining simplicity and configurability. Conky can display just
16 about anything, either on your root desktop or in its own window. Not
17 only does Conky have many built-in objects, it can also display just
18 about any piece of information by using scripts and other external pro-
21 Conky has more than 250 built in objects, including support for a
22 plethora of OS stats (uname, uptime, CPU usage, mem usage, disk usage,
23 "top" like process stats, and network monitoring, just to name a few),
24 built in IMAP and POP3 support, built in support for many popular music
25 players (MPD, XMMS2, BMPx, Audacious), and much much more. Conky can
26 display this info either as text, or using simple progress bars and
27 graph widgets, with different fonts and colours.
29 We are always looking for help, whether its reporting bugs, writing
30 patches, or writing docs. Please use the facilities at SourceForge to
31 make bug reports, feature requests, and submit patches, or stop by
32 #conky on irc.freenode.net if you have questions or want to contribute.
34 Thanks for your interest in Conky.
37 For users compiling from source on a binary distro, make sure you have
38 the X development libraries installed (Unless you provide configure
39 with "--disable-x11"). This should be a package along the lines of
40 "libx11-dev" or "xorg-x11-dev" for X11 libs, and similar "-dev" format
41 for the other libs required (depending on your configure options). You
42 should be able to see which extra packages you need to install by read-
43 ing errors that you get from './configure'. You can enable/disable
44 stuff by giving options to configure, but be careful with disabling.
45 For example: with --disable-math you won't get errors but logarithmic
46 graphs will be normal graphs and gauges will miss their line.
48 Conky has (for some time) been available in the repositories of most
49 popular distributions. Here are some installation instructions for a
52 Gentoo users -- Conky is in Gentoo's Portage... simply use "emerge
53 app-admin/conky" for installation.
55 Debian, etc. users -- Conky should be in your repositories, and can be
56 installed by doing "aptitude install conky".
58 Example to compile and run Conky with all optional components (note
59 that some configure options may differ for your system):
61 sh autogen.sh # Only required if building from the git repo
63 ./configure --prefix=/usr --mandir=/usr/share/man --in-
64 fodir=/usr/share/info --datadir=/usr/share --sysconfdir=/etc --local-
65 statedir=/var/lib --disable-own-window --enable-audacious[=yes|no|lega-
66 cy] --enable-bmpx --disable-hddtemp --disable-mpd --enable-xmms2 --dis-
67 able-portmon --disable-network --enable-debug --disable-x11 --dis-
68 able-double-buffer --disable-xdamage --disable-xft
72 make install # Optional
76 Conky has been tested to be compatible with C99 C, however it has not
77 been tested with anything other than gcc, and is not guaranteed to work
81 Conky is generally very good on resources. That said, the more you try
82 to make Conky do, the more resources it is going to consume.
84 An easy way to force Conky to reload your ~/.conkyrc: "killall -SIGUSR1
85 conky". Saves you the trouble of having to kill and then restart. You
86 can now also do the same with SIGHUP.
89 Command line options override configurations defined in configuration
93 Prints version and exits
97 Run Conky in 'quiet mode' (ie. no output)
101 Increase debugging output, ie. -DD for more debugging
104 -a | --alignment= ALIGNMENT
105 Text alignment on screen, {top,bottom,middle}_{left,right,mid-
106 dle} or none. Can also be abbreviated with first chars of posi-
107 tion, ie. tr for top_right.
111 Use double buffering (eliminates "flicker")
115 Config file to load instead of $HOME/.conkyrc
119 Print builtin default config to stdout. See also the section EX-
120 AMPLES for more information.
124 Daemonize Conky, aka fork to background
132 Prints command line help and exits
136 Create own window to draw
140 Text to render, remember single quotes, like -t ' $uptime '
143 -p | --pause= SECONDS
144 Time to pause before actually starting Conky
147 -u | --interval= SECONDS
151 -w | --window-id= WIN_ID
155 -X | --display= DISPLAY
168 Number of times to update Conky (and quit)
171 CONFIGURATION SETTINGS
172 Default configuration file location is $HOME/.conkyrc or
173 ${sysconfdir}/conky/conky.conf. On most systems, sysconfdir is /etc,
174 and you can find the sample config file there (/etc/conky/conky.conf).
176 You might want to copy it to $HOME/.conkyrc and then start modifying
177 it. Other configs can be found at http://conky.sf.net/
179 TEXT After this begins text to be formatted on screen. Backslash (\)
180 escapes newlines in the text section. This can be useful for
181 cleaning up config files where conky is used to pipe input to
186 Aligned position on screen, may be top_left, top_right, top_mid-
187 dle, bottom_left, bottom_right, bottom_middle, middle_left, mid-
188 dle_middle, middle_right, or none (also can be abreviated as tl,
189 tr, tm, bl, br, bm, ml, mm, mr). See also gap_x and gap_y.
193 Append the file given as argument.
197 Boolean value, if true, Conky will be forked to background when
202 Inner border margin in pixels (the margin between the border and
207 Outer border margin in pixels (the margin between the border and
208 the edge of the window).
212 Border width in pixels.
215 colorN Predefine a color for use inside TEXT segments. Substitute N by
216 a digit between 0 and 9, inclusively. When specifying the color
217 value in hex, omit the leading hash (#).
221 The number of samples to average for CPU monitoring.
225 Specify a default width and height for bars. Example: 'de-
226 fault_bar_size 0 6'. This is particularly useful for execbar and
227 execibar as they do not take size arguments.
231 Default color and border color
235 Specify a default width and height for gauges. Example: 'de-
236 fault_gauge_size 25 25'. This is particularly useful for exec-
237 gauge and execigauge as they do not take size arguments
241 Specify a default width and height for graphs. Example: 'de-
242 fault_graph_size 0 25'. This is particularly useful for exec-
243 graph and execigraph as they do not take size arguments
246 default_outline_color
247 Default outline color
251 Default shading color and border's shading color
255 Enable to disable the inotify-based auto config reload feature.
259 The number of samples to average for disk I/O monitoring.
263 Specify an X display to connect to.
267 Use the Xdbe extension? (eliminates flicker) It is highly recom-
268 mended to use own window with this one so double buffer won't be
273 Draw borders around text?
277 Draw borders around graphs?
289 Put an extra newline at the end when writing to stdout, useful
290 for writing to awesome's wiboxes.
293 font Font name in X, xfontsel can be used to get a nice font
296 format_human_readable
297 If enabled, values which are in bytes will be printed in human
298 readable format (i.e., KiB, MiB, etc). If disabled, the number
299 of bytes is printed instead.
302 gap_x Gap, in pixels, between right or left border of screen, same as
303 passing -x at command line, e.g. gap_x 10. For other position
304 related stuff, see 'alignment'.
307 gap_y Gap, in pixels, between top or bottom border of screen, same as
308 passing -y at command line, e.g. gap_y 10. For other position
309 related stuff, see 'alignment'.
313 Hostname to connect to for hddtemp objects. Defaults to
318 Port to use for hddtemp connections. Defaults to 7634.
322 How strict should if_up be when testing an interface for being
323 up? The value is one of up, link or address, to check for the
324 interface being solely up, being up and having link or being up,
325 having link and an assigned IP address.
328 imap Default global IMAP server. Arguments are: "host user pass [-i
329 interval (in seconds)] [-f 'folder'] [-p port] [-e 'command']
330 [-r retries]". Default port is 143, default folder is 'INBOX',
331 default interval is 5 minutes, and default number of retries be-
332 fore giving up is 5. If the password is supplied as '*', you
333 will be prompted to enter the password when Conky starts.
336 imlib_cache_flush_interval
337 Interval (in seconds) to flush Imlib2 cache.
341 Imlib2 image cache size, in bytes. Defaults to 4MiB. Increase
342 this value if you use $image lots. Set to 0 to disable the image
346 lua_draw_hook_post function_name [function arguments]
347 This function, if defined, will be called by Conky through each
348 iteration after drawing to the window. Requires X support. Takes
349 any number of optional arguments. Use this hook for drawing
350 things on top of what Conky draws. Conky puts 'conky_' in front
351 of function_name to prevent accidental calls to the wrong func-
352 tion unless you place 'conky_' in front of it yourself.
355 lua_draw_hook_pre function_name [function arguments]
356 This function, if defined, will be called by Conky through each
357 iteration before drawing to the window. Requires X support.
358 Takes any number of optional arguments. Use this hook for draw-
359 ing things on top of what Conky draws. Conky puts 'conky_' in
360 front of function_name to prevent accidental calls to the wrong
361 function unless you place 'conky_' in front of it yourself.
365 Loads the Lua scripts separated by spaces.
368 lua_shutdown_hook function_name [function arguments]
369 This function, if defined, will be called by Conky at shutdown
370 or when the configuration is reloaded. Use this hook to clean up
371 after yourself, such as freeing memory which has been allocated
372 by external libraries via Lua. Conky puts 'conky_' in front of
373 function_name to prevent accidental calls to the wrong function
374 unless you place 'conky_' in front of it yourself.
377 lua_startup_hook function_name [function arguments]
378 This function, if defined, will be called by Conky at startup or
379 when the configuration is reloaded. Use this hook to initialize
380 values, or for any run-once applications. Conky puts 'conky_' in
381 front of function_name to prevent accidental calls to the wrong
382 function unless you place 'conky_' in front of it yourself.
386 Mail spool for mail checking
389 max_port_monitor_connections
390 Allow each port monitor to track at most this many connections
391 (if 0 or not set, default is 256)
395 Maximum number of special things, e.g. fonts, offsets, aligns,
396 etc. (default is 512)
400 When a line in the output contains 'width' chars and the end
401 isn't reached, the next char will start on a new line. If you
402 want to make sure that lines don't get broken, set 'width' to 0
406 Maximum size of user text buffer, i.e. layout below TEXT line in
407 config file (default is 16384 bytes)
411 Maximum width of window
414 minimum_size width (height)
415 Minimum size of window
430 music_player_interval
431 Music player thread update interval (defaults to Conky's update
436 The number of samples to average for net data
440 Subtract (file system) buffers from used memory?
444 Print text to stdout.
448 Print text in the console, but use ncurses so that conky can
449 print the text of a new update over the old text. (In the future
450 this will provide more useful things)
454 Print text to stderr.
458 When set to no, there will be no output in X (useful when you
459 also use things like out_to_console). If you set it to no, make
460 sure that it's placed before all other X-related setting (take
461 the first line of your configfile to be sure). Default value is
466 Force UTF8? requires XFT
470 Overwrite the file given as argument.
474 Boolean, create own window to draw?
478 Manually set the WM_CLASS name. Defaults to "Conky".
481 own_window_colour colour
482 If own_window_transparent no, set a specified background colour
483 (defaults to black). Takes either a hex value (e.g. ffffff, note
484 the lack of '#') or a valid RGB name (see /usr/lib/X11/rgb.txt)
487 own_window_hints undecorated,below,above,sticky,skip_taskbar,skip_pager
488 If own_window is yes, you may use these window manager hints to
489 affect the way Conky displays. Notes: Use own_window_type desk-
490 top as another way to implement many of these hints implicitly.
491 If you use own_window_type override, window manager hints have
492 no meaning and are ignored.
496 Manually set the window name. Defaults to "<hostname> - conky".
499 own_window_argb_visual
500 Boolean, use ARGB visual? ARGB can be used for real transparen-
501 cy, note that a composite manager is required for real trans-
502 parency. This option will not work as desired (in most cases) in
503 conjunction with 'own_window_type override'.
506 own_window_argb_value
507 When ARGB visuals are enabled, this use this to modify the alpha
508 value used. Valid range is 0-255, where 0 is 0% opacity, and 255
509 is 100% opacity. Note that if own_window_transparent is enabled,
510 this value has no effect.
513 own_window_transparent
514 Boolean, set transparency? If ARGB visual is enabled, sets back-
515 ground opacity to 0%.
519 if own_window is yes, you may specify type normal, desktop,
520 dock, panel or override (default: normal). Desktop windows are
521 special windows that have no window decorations; are always vis-
522 ible on your desktop; do not appear in your pager or taskbar;
523 and are sticky across all workspaces. Panel windows reserve
524 space along a desktop edge, just like panels and taskbars, pre-
525 venting maximized windows from overlapping them. The edge is
526 chosen based on the alignment option. Override windows are not
527 under the control of the window manager. Hints are ignored. This
528 type of window can be useful for certain situations.
532 Pad percentages to this many decimals (0 = no padding)
535 pop3 Default global POP3 server. Arguments are: "host user pass [-i
536 interval (in seconds)] [-p port] [-e 'command'] [-r retries]".
537 Default port is 110, default interval is 5 minutes, and default
538 number of retries before giving up is 5. If the password is sup-
539 plied as '*', you will be prompted to enter the password when
544 Shortens units to a single character (kiB->k, GiB->G, etc.). De-
549 Shows the time range covered by a graph.
553 Shows the maximum value in scaled graphs.
557 Border stippling (dashing) in pixels
561 Desired output unit of all objects displaying a temperature. Pa-
562 rameters are either "fahrenheit" or "celsius". The default unit
567 Define a template for later use inside TEXT segments. Substitute
568 N by a digit between 0 and 9, inclusively. The value of the
569 variable is being inserted into the stuff below TEXT at the cor-
570 responding position, but before some substitutions are applied:
575 '\N' -> template argument N
578 text_buffer_size bytes
579 Size of the standard text buffer (default is 256 bytes). This
580 buffer is used for intermediary text, such as individual lines,
581 output from $exec vars, and various other variables. Increasing
582 the size of this buffer can drastically reduce Conky's perfor-
583 mance, but will allow for more text display per variable. The
584 size of this buffer cannot be smaller than the default value of
589 If true, variables that output times output a number that repre-
590 sents seconds. This doesn't affect $time, $tztime and $utime
594 If true, cpu in top will show usage of one processor's power. If
595 false, cpu in top will show the usage of all processors' power
600 Width for $top name value (defaults to 15 characters).
604 Total number of times for Conky to update before quitting. Zero
605 makes Conky run forever
608 update_interval seconds
612 update_interval_on_battery seconds
613 Update interval when running on batterypower
617 Boolean value, if true, text is rendered in upper case
621 Adds spaces around certain objects to stop them from moving oth-
622 er things around. Arguments are left, right, and none (default).
623 The old true/false values are deprecated and default to
624 right/none respectively. Note that this only helps if you are
625 using a mono font, such as Bitstream Vera Sans Mono.
629 Use Xft (anti-aliased font and stuff)
633 Alpha of Xft font. Must be a value at or between 1 and 0.
641 Colours are parsed using XParsecolor(), there might be a list of them:
642 /usr/share/X11/rgb.txt. Colour can be also in #rrggbb format (hex).
644 Some objects may create threads, and sometimes these threads will not
645 be destroyed until Conky terminates. There is no way to destroy or
646 clean up threads while Conky is running. For example, if you use an MPD
647 variable, the MPD thread will keep running until Conky dies. Some
648 threaded objects will use one of the parameters as a 'key', so that you
649 only have 1 relevant thread running (for example, the $curl, $rss and
650 $weather objects launch one thread per URI).
652 acpiacadapter (adapter)
653 ACPI ac adapter state. On linux, the adapter option specifies
654 the subfolder of /sys/class/power_supply containing the state
655 information (defaults to "AC"). Other systems ignore it.
663 ACPI temperature in C.
667 IP address for an interface, or "No Address" if no address is
672 IP addresses for an interface (if one - works like addr). Linux
677 CPU temperature from therm_adt746x
681 Fan speed from therm_adt746x
689 Right-justify text, with space of N
693 Sets up the connection to apcupsd daemon. Prints nothing, de-
694 faults to localhost:3551
698 Prints the UPS connection type.
702 Current battery capacity in percent.
706 Reason for last transfer from line to battery.
710 Nominal input voltage.
714 Current load in percent.
718 Bar showing current load.
721 apcupsd_loadgauge (height),(width)
722 Gauge that shows current load.
725 apcupsd_loadgraph (height),(width) (gradient colour 1) (gradient colour
727 History graph of current load.
731 Prints the model of the UPS.
735 Prints the UPS user-defined name.
739 Prints current status (on-line, on-battery).
743 Current internal temperature.
747 Time left to run on battery.
751 Prints the UPS mode (e.g. standalone).
755 Display APM AC adapter status (FreeBSD only)
759 Display APM battery life in percent (FreeBSD only)
763 Display remaining APM battery life in hh:mm:ss or "unknown" if
764 AC adapterstatus is on-line or charging (FreeBSD only)
767 audacious_bar (height),(width)
772 Bitrate of current tune
776 Number of audio channels of current tune
780 Full path and filename of current tune
784 Sampling frequency of current tune
788 Total length of current tune as MM:SS
791 audacious_length_seconds
792 Total length of current tune in seconds
795 audacious_main_volume
796 The current volume fetched from Audacious
799 audacious_playlist_length
800 Number of tunes in playlist
803 audacious_playlist_position
804 Playlist position of current tune
808 Position of current tune (MM:SS)
811 audacious_position_seconds
812 Position of current tune in seconds
816 Player status (Playing/Paused/Stopped/Not running)
819 audacious_title (max length)
820 Title of current tune with optional maximum length specifier
824 Battery status and remaining percentage capacity of ACPI or APM
825 battery. ACPI battery number can be given as argument (default
829 battery_bar (height),(width) (num)
830 Battery percentage remaining of ACPI battery in a bar. ACPI bat-
831 tery number can be given as argument (default is BAT0).
834 battery_percent (num)
835 Battery percentage remaining for ACPI battery. ACPI battery
836 number can be given as argument (default is BAT0).
840 Battery status and remaining percentage capacity of ACPI or APM
841 battery. ACPI battery number can be given as argument (default
842 is BAT0). This mode display a short status, which means that C
843 is displayed instead of charging, D for discharging, F for full,
844 N for not present, E for empty and U for unknown.
848 Battery charge/discharge time remaining of ACPI battery. ACPI
849 battery number can be given as argument (default is BAT0).
852 blink text_and_other_conky_vars
853 Let 'text_and_other_conky_vars' blink on and off.
857 Album in current BMPx track
861 Artist in current BMPx track
865 Bitrate of the current BMPx track
869 Title of the current BMPx track
873 Track number of the current BMPx track
877 URI of the current BMPx track
881 Amount of memory buffered
884 cached Amount of memory cached
887 cmdline_to_pid string
888 PID of the first process that has string in it's commandline
892 Change drawing color to 'color' which is a name of a color or a
893 hexcode preceded with # (for example #0A1B2C ). If you use
894 ncurses only the following colors are supported: red,green,yel-
895 low,blue,magenta,cyan,black,white.
898 colorN Change drawing color to colorN configuration option, where N is
899 a digit between 0 and 9, inclusively.
903 Places the lines of var2 to the right of the lines of var1 sepa-
904 rated by the chars that are put between var1 and var2. For exam-
905 ple: ${combine ${head /proc/cpuinfo 2} - ${head /proc/meminfo
906 1}} gives as output "cpuinfo_line1 - meminfo_line1" on line 1
907 and "cpuinfo_line2 -" on line 2. $combine vars can also be nest-
908 ed to place more vars next to each other.
912 CPU architecture Conky was built for
924 CPU usage in percents. For SMP machines, the CPU number can be
925 provided as an argument. ${cpu cpu0} is the total usage, and
926 ${cpu cpuX} (X >= 1) are individual CPUs.
929 cpubar (cpuN) (height),(width)
930 Bar that shows CPU usage, height is bar's height in pixels. See
931 $cpu for more info on SMP.
934 cpugauge (cpuN) (height),(width)
935 Elliptical gauge that shows CPU usage, height and width are
936 gauge's vertical and horizontal axis respectively. See $cpu for
940 cpugraph (cpuN) (height),(width) (gradient colour 1) (gradient colour
942 CPU usage graph, with optional colours in hex, minus the #. See
943 $cpu for more info on SMP. Uses a logarithmic scale (to see
944 small numbers) when you use the -l switch. Takes the switch '-t'
945 to use a temperature gradient, which makes the gradient values
946 change depending on the amplitude of a particular graph value
950 curl url (interval_in_minutes)
951 Download data from URI using Curl at the specified interval. The
952 interval may be a floating point value greater than 0, otherwise
953 defaults to 15 minutes. Most useful when used in conjunction
954 with Lua and the Lua API. This object is threaded, and once a
955 thread is created it can't be explicitly destroyed. One thread
956 will run for each URI specified. You can use any protocol that
960 Number of the desktop on which conky is running or the message
961 "Not running in X" if this is the case.
965 Name of the desktop on which conky is running or the message
966 "Not running in X" if this is the case.
970 Number of desktops or the message "Not running in X" if this is
975 Disk protection status, if supported (needs kernel-patch).
976 Prints either "frozen" or "free " (note the padding).
980 Displays current disk IO. Device is optional, and takes the form
981 of sda for /dev/sda. Individual partitions are allowed.
985 Displays current disk IO for reads. Device as in diskio.
988 diskio_write (device)
989 Displays current disk IO for writes. Device as in diskio.
992 diskiograph (device) (height),(width) (gradient colour 1) (gradient
993 colour 2) (scale) (-t) (-l)
994 Disk IO graph, colours defined in hex, minus the #. If scale is
995 non-zero, it becomes the scale for the graph. Uses a logarithmic
996 scale (to see small numbers) when you use -l switch. Takes the
997 switch '-t' to use a temperature gradient, which makes the gra-
998 dient values change depending on the amplitude of a particular
999 graph value (try it and see).
1002 diskiograph_read (device) (height),(width) (gradient colour 1) (gradi-
1003 ent colour 2) (scale) (-t) (-l)
1004 Disk IO graph for reads, colours defined in hex, minus the #. If
1005 scale is non-zero, it becomes the scale for the graph. Device as
1006 in diskio. Uses a logarithmic scale (to see small numbers) when
1007 you use -l switch. Takes the switch '-t' to use a temperature
1008 gradient, which makes the gradient values change depending on
1009 the amplitude of a particular graph value (try it and see).
1012 diskiograph_write (device) (height),(width) (gradient colour 1) (gradi-
1013 ent colour 2) (scale) (-t) (-l)
1014 Disk IO graph for writes, colours defined in hex, minus the #.
1015 If scale is non-zero, it becomes the scale for the graph. Device
1016 as in diskio. Uses a logarithmic scale (to see small numbers)
1017 when you use -l switch. Takes the switch '-t' to use a tempera-
1018 ture gradient, which makes the gradient values change depending
1019 on the amplitude of a particular graph value (try it and see).
1023 Download speed in suitable IEC units
1027 Download speed in KiB with one decimal
1030 downspeedgraph (netdev) (height),(width) (gradient colour 1) (gradient
1031 colour 2) (scale) (-t) (-l)
1032 Download speed graph, colours defined in hex, minus the #. If
1033 scale is non-zero, it becomes the scale for the graph. Uses a
1034 logarithmic scale (to see small numbers) when you use -l switch.
1035 Takes the switch '-t' to use a temperature gradient, which makes
1036 the gradient values change depending on the amplitude of a par-
1037 ticular graph value (try it and see).
1040 draft_mails (maildir) (interval)
1041 Number of mails marked as draft in the specified mailbox or mail
1042 spool if not. Only maildir type mailboxes are supported, mbox
1043 type will return -1.
1046 else Text to show if any of the above are not true
1049 endif Ends an $if block.
1053 Current entropy available for crypto freaks
1056 entropy_bar (height),(width)
1057 Normalized bar of available entropy for crypto freaks
1061 Percentage of entropy available in comparison to the poolsize
1065 Total size of system entropy pool for crypto freaks
1069 Evaluates given string according to the rules of TEXT interpre-
1070 tation, i.e. parsing any contained text object specifications
1071 into their output, any occuring '$$' into a single '$' and so
1072 on. The output is then being parsed again.
1075 eve api_userid api_key character_id
1076 Fetches your currently training skill from the Eve Online API
1077 servers (http://www.eve-online.com/) and displays the skill
1078 along with the remaining training time.
1082 Executes a shell command and displays the output in conky. warn-
1083 ing: this takes a lot more resources than other variables. I'd
1084 recommend coding wanted behaviour in C and posting a patch.
1088 Same as exec, except if the first value return is a value be-
1089 tween 0-100, it will use that number for a bar. The size for
1090 bars can be controlled via the default_bar_size config setting.
1094 Same as exec, except if the first value returned is a value be-
1095 tween 0-100, it will use that number for a gauge. The size for
1096 gauges can be controlled via the default_gauge_size config set-
1100 execgraph (-t) (-l) command
1101 Same as execbar, but graphs values. Uses a logaritmic scale when
1102 the log option (-l switch) is given (to see small numbers). Val-
1103 ues still have to be between 0 and 100. The size for graphs can
1104 be controlled via the default_graph_size config setting. Takes
1105 the switch '-t' to use a temperature gradient, which makes the
1106 gradient values change depending on the amplitude of a particu-
1107 lar graph value (try it and see). If -t or -l is your first ar-
1108 gument, you may need to preceed it by a space (' ').
1111 execi interval command
1112 Same as exec but with specific interval. Interval can't be less
1113 than update_interval in configuration. See also $texeci
1116 execibar interval command
1117 Same as execbar, except with an interval
1120 execigauge interval command
1121 Same as execgauge, but takes an interval arg and gauges values.
1124 execigraph interval (-t) (-l) command
1125 Same as execgraph, but takes an interval arg and graphs values.
1126 If -t or -l is your first argument, you may need to preceed it
1131 Executes a shell command and displays the output in conky. warn-
1132 ing: this takes a lot more resources than other variables. I'd
1133 recommend coding wanted behaviour in C and posting a patch. This
1134 differs from $exec in that it parses the output of the command,
1135 so you can insert things like ${color red}hi!${color} in your
1136 script and have it correctly parsed by Conky. Caveats: Conky
1137 parses and evaluates the output of $execp every time Conky
1138 loops, and then destroys all the objects. If you try to use any-
1139 thing like $execi within an $execp statement, it will function-
1140 ally run at the same interval that the $execp statement runs, as
1141 it is created and destroyed at every interval.
1144 execpi interval command
1145 Same as execp but with specific interval. Interval can't be
1146 less than update_interval in configuration. Note that the output
1147 from the $execpi command is still parsed and evaluated at every
1151 flagged_mails (maildir) (interval)
1152 Number of mails marked as flagged in the specified mailbox or
1153 mail spool if not. Only maildir type mailboxes are supported,
1154 mbox type will return -1.
1158 Specify a different font. This new font will apply to the cur-
1159 rent line and everything following. You can use a $font with no
1160 arguments to change back to the default font (much like with
1164 format_time seconds format
1165 Format time given in seconds. This var only works when the
1166 times_in_seconds configuration setting is on. Format is a string
1167 that should start and end with a "-char. The "-chars are not
1168 part of the output, \w,\d,\h,\m,\s,\(,\) and \\ are replaced by
1169 weeks,days,hours,minutes,seconds,(,) and \. If you leave out a
1170 unit, it's value will be expressed in the highest unite lower
1171 then the one left out. Text between ()-chars will not be visible
1172 if a replaced unit in this text is 0. If seconds is a decimal
1173 number then you can see the numbers behind the point by using \S
1174 followed by a number that specifies the amount of digits behind
1175 the point that you want to see (maximum 9). You can also place
1176 a 'x' behind \S so you have all digits behind the point and no
1177 trailing zero's. (also maximum 9)
1180 forwarded_mails (maildir) (interval)
1181 Number of mails marked as forwarded in the specified mailbox or
1182 mail spool if not. Only maildir type mailboxes are supported,
1183 mbox type will return -1.
1187 Returns CPU #n's frequency in MHz. CPUs are counted from 1. If
1188 omitted, the parameter defaults to 1.
1192 Returns CPU #n's frequency in GHz. CPUs are counted from 1. If
1193 omitted, the parameter defaults to 1.
1196 fs_bar (height),(width) fs
1197 Bar that shows how much space is used on a file system. height
1198 is the height in pixels. fs is any file on that file system.
1201 fs_bar_free (height),(width) fs
1202 Bar that shows how much space is free on a file system. height
1203 is the height in pixels. fs is any file on that file system.
1207 Free space on a file system available for users.
1211 Free percentage of space on a file system available for users.
1223 File system used space.
1227 Percent of file system used space.
1230 goto x The next element will be printed at position 'x'.
1234 Displays the default route's interface or "multiple"/"none" ac-
1238 gw_ip Displays the default gateway's IP or "multiple"/"none" accord-
1243 Displays temperature of a selected hard disk drive as reported
1244 by the hddtemp daemon. Use hddtemp_host and hddtemp_port to
1245 specify a host and port for all hddtemp objects. If no dev pa-
1246 rameter is given, the first disk returned by the hddtemp daemon
1250 head logfile lines (next_check)
1251 Displays first N lines of supplied text file. The file is
1252 checked every 'next_check' update. If next_check is not sup-
1253 plied, Conky defaults to 2. Max of 30 lines can be displayed, or
1254 until the text buffer is filled.
1258 Horizontal line, height is the height in pixels
1261 hwmon (dev) type n (factor offset)
1262 Hwmon sensor from sysfs (Linux 2.6). Parameter dev may be omit-
1263 ted if you have only one hwmon device. Parameter type is either
1264 'in' or 'vol' meaning voltage; 'fan' meaning fan; 'temp' meaning
1265 temperature. Parameter n is number of the sensor. See
1266 /sys/class/hwmon/ on your local computer. The optional arguments
1267 'factor' and 'offset' allow precalculation of the raw input,
1268 which is being modified as follows: 'input = input * factor +
1269 offset'. Note that they have to be given as decimal values (i.e.
1270 contain at least one decimal place).
1273 i2c (dev) type n (factor offset)
1274 I2C sensor from sysfs (Linux 2.6). Parameter dev may be omitted
1275 if you have only one I2C device. Parameter type is either 'in'
1276 or 'vol' meaning voltage; 'fan' meaning fan; 'temp' meaning tem-
1277 perature. Parameter n is number of the sensor. See
1278 /sys/bus/i2c/devices/ on your local computer. The optional argu-
1279 ments 'factor' and 'offset' allow precalculation of the raw in-
1280 put, which is being modified as follows: 'input = input * factor
1281 + offset'. Note that they have to be given as decimal values
1282 (i.e. contain at least one decimal place).
1286 If running the i8k kernel driver for Inspiron laptops, displays
1287 whether ac power is on, as listed in /proc/i8k (translated to
1288 human-readable). Beware that this is by default not enabled by
1293 If running the i8k kernel driver for Inspiron laptops, displays
1294 the bios version as listed in /proc/i8k.
1298 If running the i8k kernel driver for Inspiron laptops, displays
1299 the volume buttons status as listed in /proc/i8k.
1303 If running the i8k kernel driver for Inspiron laptops, displays
1304 the cpu temperature in Celsius, as reported by /proc/i8k.
1308 If running the i8k kernel driver for Inspiron laptops, displays
1309 the left fan's rate of rotation, in revolutions per minute as
1310 listed in /proc/i8k. Beware, some laptops i8k reports these fans
1315 If running the i8k kernel driver for Inspiron laptops, displays
1316 the left fan status as listed in /proc/i8k (translated to human-
1317 readable). Beware, some laptops i8k reports these fans in re-
1322 If running the i8k kernel driver for Inspiron laptops, displays
1323 the right fan's rate of rotation, in revolutions per minute as
1324 listed in /proc/i8k. Beware, some laptops i8k reports these fans
1328 i8k_right_fan_status
1329 If running the i8k kernel driver for Inspiron laptops, displays
1330 the right fan status as listed in /proc/i8k (translated to hu-
1331 man-readable). Beware, some laptops i8k reports these fans in
1336 If running the i8k kernel driver for Inspiron laptops, displays
1337 your laptop serial number as listed in /proc/i8k.
1341 If running the i8k kernel driver for Inspiron laptops, displays
1342 the version formatting of /proc/i8k.
1346 If running the IBM ACPI, displays the brigtness of the laptops's
1351 If running the IBM ACPI, displays the fan speed.
1355 If running the IBM ACPI, displays the temperatures from the IBM
1356 temperature sensors (N=0..7) Sensor 0 is on the CPU, 3 is on the
1361 If running the IBM ACPI, displays the "master" volume, con-
1362 trolled by the volume keys (0-14).
1365 iconv_start codeset_from codeset_to
1366 Convert text from one codeset to another using GNU iconv. Needs
1367 to be stopped with iconv_stop.
1371 Stop iconv codeset conversion.
1375 if conky variable VAR is empty, display everything between
1376 $if_empty and the matching $endif
1379 if_existing file (string)
1380 if FILE exists, display everything between if_existing and the
1381 matching $endif. The optional second paramater checks for FILE
1382 containing the specified string and prints everything between
1383 $if_existing and the matching $endif.
1386 if_gw if there is at least one default gateway, display everything be-
1387 tween $if_gw and the matching $endif
1391 Evaluates the given boolean expression, printing everything be-
1392 tween $if_match and the matching $endif depending on whether the
1393 evaluation returns true or not. Valid expressions consist of a
1394 left side, an operator and a right side. Left and right sides
1395 are being parsed for contained text objects before evaluation.
1396 Recognised left and right side types are:
1398 doubleArgument consists of only digits and a single dot.
1399 longArgument consists of only digits.
1400 stringArgument is enclosed in quotation marks (")
1402 Valid operands are: '>', '<', '>=', '<=', '==', '!='.
1405 if_mixer_mute (mixer)
1406 If mixer exists, display everything between $if_mixer_mute and
1407 the matching $endif. If no mixer is specified, "Master" is used.
1410 if_mounted (mountpoint)
1411 if MOUNTPOINT is mounted, display everything between $if_mounted
1412 and the matching $endif
1416 if mpd is playing or paused, display everything between
1417 $if_mpd_playing and the matching $endif
1420 if_running (process)
1421 if PROCESS is running, display everything $if_running and the
1422 matching $endif. This uses the ``pidof'' command, so the -x
1423 switch is also supported.
1426 if_smapi_bat_installed (INDEX)
1427 when using smapi, if the battery with index INDEX is installed,
1428 display everything between $if_smapi_bat_installed and the
1433 if INTERFACE exists and is up, display everything between $if_up
1434 and the matching $endif
1437 if_updatenr (updatenr)
1438 If it's the UPDATENR-th time that conky updates, display every-
1439 thing between $if_updatenr and the matching $endif. The counter
1440 resets when the highest UPDATENR is reached. Example : "{$if_up-
1441 datenr 1}foo$endif{$if_updatenr 2}bar$endif{$if_updatenr 4}$en-
1442 dif" shows foo 25% of the time followed by bar 25% of the time
1443 followed by nothing the other half of the time.
1447 Display everything between $if_xmms2_connected and the matching
1448 $endif if xmms2 is running.
1451 image <path to image> (-p x,y) (-s WxH) (-n) (-f interval)
1452 Renders an image from the path specified using Imlib2. Takes 4
1453 optional arguments: a position, a size, a no-cache switch, and a
1454 cache flush interval. Changing the x,y position will move the
1455 position of the image, and changing the WxH will scale the im-
1456 age. If you specify the no-cache flag (-n), the image will not
1457 be cached. Alternately, you can specify the -f int switch to
1458 specify a cache flust interval for a particular image. Example:
1459 ${image /home/brenden/cheeseburger.jpg -p 20,20 -s 200x200} will
1460 render 'cheeseburger.jpg' at (20,20) scaled to 200x200 pixels.
1461 Conky does not make any attempt to adjust the position (or any
1462 other formatting) of images, they are just rendered as per the
1463 arguments passed. The only reason $image is part of the TEXT
1464 section, is to allow for runtime modifications, through $execp
1465 $lua_parse, or some other method.
1468 imap_messages (args)
1469 Displays the number of messages in your global IMAP inbox by de-
1470 fault. You can define individual IMAP inboxes separately by
1471 passing arguments to this object. Arguments are: "host user
1472 pass [-i interval (in seconds)] [-f 'folder'] [-p port] [-e
1473 'command'] [-r retries]". Default port is 143, default folder is
1474 'INBOX', default interval is 5 minutes, and default number of
1475 retries before giving up is 5. If the password is supplied as
1476 '*', you will be prompted to enter the password when Conky
1481 Displays the number of unseen messages in your global IMAP inbox
1482 by default. You can define individual IMAP inboxes separately by
1483 passing arguments to this object. Arguments are: "host user pass
1484 [-i interval (in seconds)] [-f 'folder'] [-p port] [-e 'com-
1485 mand'] [-r retries]". Default port is 143, default folder is
1486 'INBOX', default interval is 5 minutes, and default number of
1487 retries before giving up is 5. If the password is supplied as
1488 '*', you will be prompted to enter the password when Conky
1493 Loads the configfile at path, places the configsettings behind
1494 the configsettings in the orginal config and places the vars
1495 where the includevar stood.
1498 Prints the current ioscheduler used for the given disk name
1499 (i.e. e.g. "hda" or "sdb")
1502 kernel Kernel version
1506 The value of /proc/sys/vm/laptop_mode
1510 Displays the number of lines in the given file
1514 System load average, 1 is for past 1 minute, 2 for past 5 min-
1515 utes and 3 for past 15 minutes. Without argument, prints all
1516 three values separated by whitespace.
1519 loadgraph (height),(width) (gradient colour 1) (gradient colour 2)
1521 Load1 average graph, similar to xload, with optional colours in
1522 hex, minus the #. Uses a logarithmic scale (to see small num-
1523 bers) when you use the -l switch. Takes the switch '-t' to use
1524 a temperature gradient, which makes the gradient values change
1525 depending on the amplitude of a particular graph value (try it
1529 lua function_name (function parameters)
1530 Executes a Lua function with given parameters, then prints the
1531 returned string. See also 'lua_load' on how to load scripts.
1532 Conky puts 'conky_' in front of function_name to prevent acci-
1533 dental calls to the wrong function unless you put you place
1534 'conky_' in front of it yourself.
1537 lua_bar (height, width) function_name (function parameters)
1538 Executes a Lua function with given parameters and draws a bar.
1539 Expects result value to be an integer between 0 and 100. See al-
1540 so 'lua_load' on how to load scripts. Conky puts 'conky_' in
1541 front of function_name to prevent accidental calls to the wrong
1542 function unless you put you place 'conky_' in front of it your-
1546 lua_gauge (height, width) function_name (function parameters)
1547 Executes a Lua function with given parameters and draws a gauge.
1548 Expects result value to be an integer between 0 and 100. See al-
1549 so 'lua_load' on how to load scripts. Conky puts 'conky_' in
1550 front of function_name to prevent accidental calls to the wrong
1551 function unless you put you place 'conky_' in front of it your-
1555 lua_graph function_name (height),(width) (gradient colour 1) (gradient
1556 colour 2) (scale) (-t) (-l)
1557 Executes a Lua function with and draws a graph. Expects result
1558 value to be any number, and by default will scale to show the
1559 full range. See also 'lua_load' on how to load scripts. Takes
1560 the switch '-t' to use a temperature gradient, which makes the
1561 gradient values change depending on the amplitude of a particu-
1562 lar graph value (try it and see). Conky puts 'conky_' in front
1563 of function_name to prevent accidental calls to the wrong func-
1564 tion unless you put you place 'conky_' in front of it yourself.
1567 lua_parse function_name (function parameters)
1568 Executes a Lua function with given parameters as per $lua, then
1569 parses and prints the result value as per the syntax for Conky's
1570 TEXT section. See also 'lua_load' on how to load scripts. Conky
1571 puts 'conky_' in front of function_name to prevent accidental
1572 calls to the wrong function unless you put you place 'conky_' in
1573 front of it yourself.
1577 Machine, i686 for example
1580 mails (mailbox) (interval)
1581 Mail count in the specified mailbox or your mail spool if not.
1582 Both mbox and maildir type mailboxes are supported. You can use
1583 a program like fetchmail to get mails from some server using
1584 your favourite protocol. See also new_mails.
1587 mboxscan (-n number of messages to print) (-fw from width) (-sw subject
1589 Print a summary of recent messages in an mbox format mailbox.
1590 mbox parameter is the filename of the mailbox (can be encapsu-
1591 lated using '"', ie. ${mboxscan -n 10 "/home/brenden/some box"}
1594 mem Amount of memory in use
1597 membar (height),(width)
1598 Bar that shows amount of memory in use
1602 Amount of free memory including the memory that is very easily
1603 freed (buffers/cache)
1607 Amount of free memory
1610 memgauge (height),(width)
1611 Gauge that shows amount of memory in use (see cpugauge)
1614 memgraph (height),(width) (gradient colour 1) (gradient colour 2)
1616 Memory usage graph. Uses a logarithmic scale (to see small num-
1617 bers) when you use the -l switch. Takes the switch '-t' to use a
1618 temperature gradient, which makes the gradient values change de-
1619 pending on the amplitude of a particular graph value (try it and
1623 memmax Total amount of memory
1627 Percentage of memory in use
1631 Prints the mixer value as reported by the OS. Default mixer is
1632 "Master", but you can specify one of the available ALSA Simple
1633 mixer controls. You can find the list of those available on
1634 your system using amixer.
1638 Displays mixer value in a bar as reported by the OS. See docs
1639 for $mixer for details on arguments.
1643 Prints the left channel mixer value as reported by the OS. See
1644 docs for $mixer for details on arguments.
1648 Displays the left channel mixer value in a bar as reported by
1649 the OS. See docs for $mixer for details on arguments.
1653 Prints the right channel mixer value as reported by the OS. See
1654 docs for $mixer for details on arguments.
1658 Displays the right channel mixer value in a bar as reported by
1659 the OS. See docs for $mixer for details on arguments.
1663 Album of the current MOC song
1667 Artist of the current MOC song
1671 Bitrate in the current MOC song
1675 Current time of the current MOC song
1679 File name of the current MOC song
1683 Rate of the current MOC song
1687 The current song name being played in MOC.
1691 Current state of MOC; playing, stopped etc.
1695 Time left in the current MOC song
1699 Title of the current MOC song
1703 Total length of the current MOC song
1707 Number of the monitor on which conky is running or the message
1708 "Not running in X" if this is the case.
1712 Number of monitors or the message "Not running in X" if this is
1717 Album in current MPD song
1721 Artist in current MPD song must be enabled at compile
1724 mpd_bar (height),(width)
1725 Bar of mpd's progress
1729 Bitrate of current song
1737 Prints the file name of the current MPD song
1745 Prints the MPD name field
1749 Percent of song's progress
1753 Random status (On/Off)
1757 Repeat status (On/Off)
1760 mpd_smart (max length)
1761 Prints the song name in either the form "artist - title" or file
1762 name, depending on whats available
1766 Playing, stopped, et cetera.
1769 mpd_title (max length)
1770 Title of current MPD song
1774 Prints the MPD track field
1782 Print a nameserver from /etc/resolv.conf. Index starts at and
1786 new_mails (mailbox) (interval)
1787 Unread mail count in the specified mailbox or mail spool if not.
1788 Both mbox and maildir type mailboxes are supported.
1795 nvidia threshold temp ambient gpufreq memfreq imagequality
1796 Nvidia graficcard support for the XNVCtrl library. Each option
1797 can be shortened to the least significant part. Temperatures are
1798 printed as float, all other values as integer.
1800 threshold The thresholdtemperature at which the gpu slows down
1801 temp Gives the gpu current temperature
1802 ambient Gives current air temperature near GPU case
1803 gpufreq Gives the current gpu frequency
1804 memfreq Gives the current mem frequency
1805 imagequality Which imagequality should be chosen by OpenGL ap-
1810 Move text over by N pixels. See also $voffset.
1813 outlinecolor (color)
1814 Change outline color
1818 If running on Apple powerbook/ibook, display information on bat-
1819 tery status. The item parameter specifies, what information to
1820 display. Exactly one item must be specified. Valid items are:
1822 status Display if battery is fully charged, charging, discharg-
1823 ing or absent (running on AC)
1824 percent Display charge of battery in percent, if charging or
1825 discharging. Nothing will be displayed, if battery is fully
1827 time Display the time remaining until the battery will be fully
1828 charged or discharged at current rate. Nothing is displayed, if
1829 battery is absent or if it's present but fully charged and not
1834 Directory used as rootdirectory by the process (this will be "/"
1835 unless the process did a chroot syscall)
1839 Command line this process was invoked with
1843 Current working directory of the process
1846 pid_environ pid varname
1847 Contents of a environment-var of the process
1850 pid_environ_list pid
1851 List of environment-vars that the process can see
1855 Path to executed command that started the process
1859 The nice value of the process
1863 List of files that the process has open
1867 The pid of the parent of the process
1871 The priority of the process (see 'priority' in "man 5 proc")
1875 Total number of bytes read by the process
1879 State of the process
1883 One of the chars in "RSDZTW" representing the state of the
1884 process where R is running, S is sleeping in an interruptible
1885 wait, D is waiting in uninterruptible disk sleep, Z is zombie, T
1886 is traced or stopped (on a signal), and W is paging
1890 Filedescriptor binded to the STDERR of the process
1894 Filedescriptor binded to the STDIN of the process
1898 Filedescriptor binded to the STDOUT of the process
1902 Number of threads in process containing this thread
1906 List with pid's from threads from this process
1909 pid_time_kernelmode pid
1910 Amount of time that the process has been scheduled in kernel
1914 pid_time_usermode pid
1915 Amount of time that the process has been scheduled in user mode
1920 Sum of $pid_time_kernelmode and $pid_time_usermode
1924 The real uid of the process
1928 The effective uid of the process
1932 The saved set uid of the process
1936 The file system uid of the process
1940 The real gid of the process
1944 The effective gid of the process
1948 The saved set gid of the process
1952 The file system gid of the process
1956 Peak virtual memory size of the process
1960 Virtual memory size of the process
1964 Locked memory size of the process
1968 Peak resident set size ("high water mark") of the process
1972 Resident set size of the process
1976 Data segment size of the process
1980 Stack segment size of the process
1984 Text segment size of the process
1988 Shared library code size of the process
1992 Page table entries size of the process
1996 Total number of bytes written by the process
1999 platform (dev) type n (factor offset)
2000 Platform sensor from sysfs (Linux 2.6). Parameter dev may be
2001 omitted if you have only one platform device. Platform type is
2002 either 'in' or 'vol' meaning voltage; 'fan' meaning fan; 'temp'
2003 meaning temperature. Parameter n is number of the sensor. See
2004 /sys/bus/platform/devices/ on your local computer. The optional
2005 arguments 'factor' and 'offset' allow precalculation of the raw
2006 input, which is being modified as follows: 'input = input * fac-
2007 tor + offset'. Note that they have to be given as decimal values
2008 (i.e. contain at least one decimal place).
2012 Displays the number of unseen messages in your global POP3 inbox
2013 by default. You can define individual POP3 inboxes separately by
2014 passing arguments to this object. Arguments are: "host user pass
2015 [-i interval (in seconds)] [-p port] [-e 'command'] [-r re-
2016 tries]". Default port is 110, default interval is 5 minutes, and
2017 default number of retries before giving up is 5. If the password
2018 is supplied as '*', you will be prompted to enter the password
2023 Displays the amount of space (in MiB, 2^20) used in your global
2024 POP3 inbox by default. You can define individual POP3 inboxes
2025 separately by passing arguments to this object. Arguments are:
2026 "host user pass [-i interval (in seconds)] [-p port] [-e 'com-
2027 mand'] [-r retries]". Default port is 110, default interval is 5
2028 minutes, and default number of retries before giving up is 5. If
2029 the password is supplied as '*', you will be prompted to enter
2030 the password when Conky starts.
2033 pre_exec shell command
2034 Executes a shell command one time before conky displays anything
2035 and puts output as text.
2039 Total processes (sleeping and running)
2042 read_tcp (host) port
2043 Connects to a tcp port on a host (default is localhost), reads
2044 every char available at the moment and shows them.
2047 replied_mails (maildir) (interval)
2048 Number of mails marked as replied in the specified mailbox or
2049 mail spool if not. Only maildir type mailboxes are supported,
2050 mbox type will return -1.
2053 rss uri interval_in_minutes action (num_par (spaces_in_front))
2054 Download and parse RSS feeds. The interval may be a floating
2055 point value greater than 0, otherwise defaults to 15 minutes.
2056 Action may be one of the following: feed_title, item_title (with
2057 num par), item_desc (with num par) and item_titles (when using
2058 this action and spaces_in_front is given conky places that many
2059 spaces in front of each item). This object is threaded, and once
2060 a thread is created it can't be explicitly destroyed. One thread
2061 will run for each URI specified. You can use any protocol that
2065 Running processes (not sleeping), requires Linux 2.6
2069 Number of running (runnable) threads. Linux only.
2072 scroll length (step) text
2073 Scroll 'text' by 'step' characters showing 'length' number of
2074 characters at the same time. The text may also contain vari-
2075 ables. 'step' is optional and defaults to 1 if not set. If a var
2076 creates output on multiple lines then the lines are placed be-
2077 hind each other separated with a '|'-sign. If you change the
2078 textcolor inside $scroll it will automatically have it's old
2079 value back at the end of $scroll. The end and the start of text
2080 will be separated by 'length' number of spaces.
2083 seen_mails (maildir) (interval)
2084 Number of mails marked as seen in the specified mailbox or mail
2085 spool if not. Only maildir type mailboxes are supported, mbox
2086 type will return -1.
2090 Change shading color
2094 when using smapi, display contents of the /sys/devices/plat-
2095 form/smapi directory. ARGS are either '(FILENAME)' or 'bat (IN-
2096 DEX) (FILENAME)' to display the corresponding files' content.
2097 This is a very raw method of accessing the smapi values. When
2098 available, better use one of the smapi_* variables instead.
2101 smapi_bat_bar (INDEX),(height),(width)
2102 when using smapi, display the remaining capacity of the battery
2103 with index INDEX as a bar.
2106 smapi_bat_perc (INDEX)
2107 when using smapi, display the remaining capacity in percent of
2108 the battery with index INDEX. This is a separate variable be-
2109 cause it supports the 'use_spacer' configuration option.
2112 smapi_bat_power INDEX
2113 when using smapi, display the current power of the battery with
2114 index INDEX in watt. This is a separate variable because the
2115 original read out value is being converted from mW. The sign of
2116 the output reflects charging (positive) or discharging (nega-
2120 smapi_bat_temp INDEX
2121 when using smapi, display the current temperature of the battery
2122 with index INDEX in degree Celsius. This is a separate variable
2123 because the original read out value is being converted from mil-
2128 Displays the Sony VAIO fanspeed information if sony-laptop ker-
2129 nel support is enabled. Linux only.
2133 Stippled (dashed) horizontal line
2136 swap Amount of swap in use
2139 swapbar (height),(width)
2140 Bar that shows amount of swap in use
2148 Total amount of swap
2152 Percentage of swap in use
2156 System name, Linux for example
2159 tab (width, (start))
2160 Puts a tab of the specified width, starting from column 'start'.
2161 The unit is pixels for both arguments.
2164 tail logfile lines (next_check)
2165 Displays last N lines of supplied text file. The file is checked
2166 every 'next_check' update. If next_check is not supplied, Conky
2167 defaults to 2. Max of 30 lines can be displayed, or until the
2168 text buffer is filled.
2171 tcp_portmon port_begin port_end item (index)
2172 TCP port (both IPv6 and IPv4) monitor for specified local ports.
2173 Port numbers must be in the range 1 to 65535. Valid items are:
2175 count Total number of connections in the range
2176 rip Remote ip address
2177 rhost Remote host name
2178 rport Remote port number
2179 rservice Remote service name from /etc/services
2180 lip Local ip address
2181 lhost Local host name
2182 lport Local port number
2183 lservice Local service name from /etc/services
2185 The connection index provides you with access to each connection
2186 in the port monitor. The monitor will return information for in-
2187 dex values from 0 to n-1 connections. Values higher than n-1 are
2188 simply ignored. For the "count" item, the connection index must
2189 be omitted. It is required for all other items.
2193 ${tcp_portmon 6881 6999 count} Displays the number of connec-
2194 tions in the bittorrent port range
2195 ${tcp_portmon 22 22 rip 0} Displays the remote host ip of the
2196 first sshd connection
2197 ${tcp_portmon 22 22 rip 9} Displays the remote host ip of the
2198 tenth sshd connection
2199 ${tcp_portmon 1 1024 rhost 0} Displays the remote host name of
2200 the first connection on a privileged port
2201 ${tcp_portmon 1 1024 rport 4} Displays the remote host port of
2202 the fifth connection on a privileged port
2203 ${tcp_portmon 1 65535 lservice 14} Displays the local service
2204 name of the fifteenth connection in the range of all ports
2206 Note that port monitor variables which share the same port range
2207 actually refer to the same monitor, so many references to a sin-
2208 gle port range for different items and different indexes all use
2209 the same monitor internally. In other words, the program avoids
2210 creating redundant monitors.
2212 templateN (arg1) (arg2) (arg3 ...)
2213 Evaluate the content of the templateN configuration variable
2214 (where N is a value between 0 and 9, inclusively), applying sub-
2215 stitutions as described in the documentation of the correspond-
2216 ing configuration variable. The number of arguments is optional,
2217 but must match the highest referred index in the template. You
2218 can use the same special sequences in each argument as the ones
2219 valid for a template definition, e.g. to allow an argument to
2220 contain a whitespace. Also simple nesting of templates is possi-
2223 Here are some examples of template definitions:
2226 template1 \1: ${fs_used \2} / ${fs_size \2}
2229 The following list shows sample usage of the templates defined
2230 above, with the equivalent syntax when not using any template at
2233 using template same without template
2234 \94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94
2235 ${template0 node name} $nodename
2236 ${template1 root /} root: ${fs_free /} /
2238 ${template1 ${template2\ disk root: ${fs_free /} /
2239 disk\ root} /} ${fs_size /}
2241 texeci interval command
2242 Runs a command at an interval inside a thread and displays the
2243 output. Same as $execi, except the command is run inside a
2244 thread. Use this if you have a slow script to keep Conky updat-
2245 ing. You should make the interval slightly longer then the time
2246 it takes your script to execute. For example, if you have a
2247 script that take 5 seconds to execute, you should make the in-
2248 terval at least 6 seconds. See also $execi. This object will
2249 clean up the thread when it is destroyed, so it can safely be
2250 used in a nested fashion, though it may not produce the desired
2251 behaviour if used this way.
2259 Local time, see man strftime to get more information about for-
2264 If 'size' is a number followed by a size-unit (kilo-
2265 byte,mb,GiB,...) then it converts the size to bytes and shows it
2266 without unit, otherwise it just shows 'size'.
2270 This takes arguments in the form:top (name) (number) Basically,
2271 processes are ranked from highest to lowest in terms of cpu us-
2272 age, which is what (num) represents. The types are: "name",
2273 "pid", "cpu", "mem", "mem_res", "mem_vsize", "time", "io_perc",
2274 "io_read" and "io_write". There can be a max of 10 processes
2279 Same as top, except sorted by the amount of I/O the process has
2280 done during the update interval
2284 Same as top, except sorted by mem usage instead of cpu
2288 Same as top, except sorted by total CPU time instead of current
2293 Total download, overflows at 4 GB on Linux with 32-bit arch and
2294 there doesn't seem to be a way to know how many times it has al-
2295 ready done that before conky has started.
2299 Total upload, this one too, may overflow
2302 trashed_mails (maildir) (interval)
2303 Number of mails marked as trashed in the specified mailbox or
2304 mail spool if not. Only maildir type mailboxes are supported,
2305 mbox type will return -1.
2308 tztime (timezone (format))
2309 Local time for specified timezone, see man strftime to get more
2310 information about format. The timezone argument is specified in
2311 similar fashion as TZ environment variable. For hints, look in
2312 /usr/share/zoneinfo. e.g. US/Pacific, Europe/Zurich, etc.
2316 Name of group with this gid
2320 Username of user with this uid
2323 unflagged_mails (maildir) (interval)
2324 Number of mails not marked as flagged in the specified mailbox
2325 or mail spool if not. Only maildir type mailboxes are supported,
2326 mbox type will return -1.
2329 unforwarded_mails (maildir) (interval)
2330 Number of mails not marked as forwarded in the specified mailbox
2331 or mail spool if not. Only maildir type mailboxes are supported,
2332 mbox type will return -1.
2335 unreplied_mails (maildir) (interval)
2336 Number of mails not marked as replied in the specified mailbox
2337 or mail spool if not. Only maildir type mailboxes are supported,
2338 mbox type will return -1.
2341 unseen_mails (maildir) (interval)
2342 Number of new or unseen mails in the specified mailbox or mail
2343 spool if not. Only maildir type mailboxes are supported, mbox
2344 type will return -1.
2347 updates Number of updates
2352 Upload speed in suitable IEC units
2356 Upload speed in KiB with one decimal
2359 upspeedgraph (netdev) (height),(width) (gradient colour 1) (gradient
2360 colour 2) (scale) (-t) (-l)
2361 Upload speed graph, colours defined in hex, minus the #. If
2362 scale is non-zero, it becomes the scale for the graph. Uses a
2363 logarithmic scale (to see small numbers) when you use the -l
2364 switch. Takes the switch '-t' to use a temperature gradient,
2365 which makes the gradient values change depending on the ampli-
2366 tude of a particular graph value (try it and see).
2373 Uptime in a shorter format
2377 Lists the names of the users logged in
2381 Number of users logged in
2385 Lists the consoles in use
2389 Lists how long users have been logged in for
2393 Lists how long the user for the given console has been logged in
2398 Display time in UTC (universal coordinate time).
2402 Change vertical offset by N pixels. Negative values will cause
2403 text to overlap. See also $offset.
2407 Returns CPU #n's voltage in mV. CPUs are counted from 1. If
2408 omitted, the parameter defaults to 1.
2412 Returns CPU #n's voltage in V. CPUs are counted from 1. If omit-
2413 ted, the parameter defaults to 1.
2416 weather URI locID data_type (interval_in_minutes)
2417 Download, parse and display METAR data.
2419 For the 'URI', there are two possibilities:
2421 http://weather.noaa.gov/pub/data/observations/metar/stations/
2422 http://xoap.weather.com/weather/local/
2424 The first one is free to use but the second requires you to reg-
2425 ister and obtain your partner ID and license key. These two must
2426 be written, separated by a space, into a file called .xoaprc
2427 which needs to be placed into your home directory.
2429 'locID' must be a valid location identifier for the required
2430 uri. For the NOAA site this must be a valid ICAO (see for in-
2431 stance https://pilotweb.nas.faa.gov/qryhtml/icao/). For the
2432 weather.com site this must be a valid location ID (see for in-
2433 stance http://aspnetresources.com/tools/locid.aspx).
2435 'data_type' must be one of the following:
2437 last_update The date and time stamp of the data. The result de-
2438 pends on the URI used. For the NOAA site it is date (yyyy/mm/dd)
2439 and UTC time. For the weather.com one it is date ([m]m/[d]d/yy)
2440 and Local Time of the station.
2443 Air temperature (you can use the 'temperature_unit' config set-
2444 ting to change units)
2447 The highest cloud cover status
2450 Air pressure in millibar
2459 Compass wind direction
2462 Relative humidity in %
2465 Any relevant weather event (rain, snow, etc.). This is not used
2466 if you are querying the weather.com site since this data is ag-
2467 gregated into the cloud_cover one
2470 Weather icon (only for www.weather.com). Can be used together
2471 with the icon kit provided upon registering to their service.
2473 'delay_in_minutes' (optional, default 30) cannot be less than 30
2476 This object is threaded, and once a thread is created it can't
2477 be explicitly destroyed. One thread will run for each URI speci-
2480 Note that these variables are still EXPERIMENTAL and can be sub-
2481 ject to many future changes.
2483 weather_forecast URI locID day data_type (interval_in_minutes)
2484 Download, parse and display weather forecast data for a given
2487 For the 'URI', for the time being only http://xoap.weath-
2488 er.com/weather/local/ is supported. See 'weather' above for de-
2491 'locID', see 'weather' above.
2493 'day' is a number from 0 (today) to 4 (3 days after tomorrow).
2495 'data_type' must be one of the following:
2498 date Date, in the form MMM DD (ie. Jul 14)
2499 low Minimun temperature (you can use the 'temperature_unit' con-
2500 fig setting to change units)
2501 hi Maximum temperature (you can use the 'temperature_unit' con-
2502 fig setting to change units)
2503 icon Weather icon. Can be used together with the icon kit pro-
2504 vided upon registering to the weather.com service
2505 forecast Weather forecast (sunny, rainy, etc.)
2506 wind_speed Wind speed in km/h
2507 wind_dir Wind direction
2508 wind_dir_DEG Compass wind direction
2509 humidity Relative humidity in %
2510 precipitation Probability of having a precipitation (in %)
2512 'delay_in_minutes' (optional, default 210) cannot be lower than
2515 This object is threaded, and once a thread is created it can't
2516 be explicitly destroyed. One thread will run for each URI speci-
2517 fied. You can use any protocol that Curl supports.
2519 Note that these variables are still EXPERIMENTAL and can be sub-
2520 ject to many future changes.
2523 Wireless access point MAC address (Linux only)
2526 wireless_bitrate (net)
2527 Wireless bitrate (ie 11 Mb/s) (Linux only)
2530 wireless_essid (net)
2531 Wireless access point ESSID (Linux only)
2534 wireless_link_bar (height),(width) (net)
2535 Wireless link quality bar (Linux only)
2538 wireless_link_qual (net)
2539 Wireless link quality (Linux only)
2542 wireless_link_qual_max (net)
2543 Wireless link quality maximum value (Linux only)
2546 wireless_link_qual_perc (net)
2547 Wireless link quality in percents (Linux only)
2551 Wireless mode (Managed/Ad-Hoc/Master) (Linux only)
2555 Displays the number of words in the given file
2559 Album in current XMMS2 song
2563 Artist in current XMMS2 song
2566 xmms2_bar (height),(width)
2567 Bar of XMMS2's progress
2571 Bitrate of current song
2575 Comment in current XMMS2 song
2579 Returns song's date.
2583 Duration of current song
2591 Genre in current XMMS2 song
2595 XMMS2 id of current song
2599 Percent of song's progress
2603 Returns the XMMS2 playlist.
2607 Size of current song
2611 Prints the song name in either the form "artist - title" or file
2612 name, depending on whats available
2616 XMMS2 status (Playing, Paused, Stopped, or Disconnected)
2620 Number of times a song was played (presumably).
2624 Title in current XMMS2 song
2628 Track number in current XMMS2 song
2632 Full path to current song
2636 Conky features a Lua Programming API, and also ships with Lua bindings
2637 for some useful libraries. Conky defines certain global functions and
2638 variables which can be accessed from Lua code running in Conky.
2640 To use Lua Conky, you first need to make sure you have a version of
2641 Conky with Lua support enabled (``conky -v'' will report this). Scripts
2642 must first be loaded using the lua_load configuration option. You then
2643 call functions in Lua via Conky's $lua, $lua_read, and Lua hooks.
2645 Be careful when creating threaded objects through the Lua API. You
2646 could wind up with a whole bunch of threads running if a thread is cre-
2647 ated with each iteration.
2649 At this time, the Lua API should not be considered stable and may
2650 change drastically from one release to another as it matures.
2652 NOTE: In order to accommodate certain features in the cairo library's
2653 API, Conky will export a few additional functions for the creation of
2654 certain structures. These are documented below.
2656 conky_parse(string) function
2657 This function takes a string that is evaluated as per Conky's
2658 TEXT section, and then returns a string with the result.
2660 conky_set_update_interval(number) function
2661 Sets Conky's update interval (in seconds) to 'number'.
2664 This table contains some information about Conky's window. The
2665 following table describes the values contained:
2667 drawable Window's drawable (Xlib Drawable), requires Lua extras
2668 enabled at compile time.
2669 visual Window's visual (Xlib Visual), requires Lua extras en-
2670 abled at compile time.
2671 display Window's display (Xlib Display), requires Lua extras en-
2672 abled at compile time.
2673 width Window width (in pixels).
2674 height Window height (in pixels).
2675 border_inner_margin Window's inner border margin (in pixels).
2676 border_outer_margin Window's outer border margin (in pixels).
2677 border_width Window's border width (in pixels).
2678 text_start_x The x component of the starting coordinate of text
2680 text_start_y The y component of the starting coordinate of text
2682 text_width The width of the text drawing region.
2683 text_height The height of the text drawing region.
2685 NOTE: This table is only defined when X support is enabled.
2688 This table contains some information about Conky's internal da-
2689 ta. The following table describes the values contained:
2691 update_interval Conky's update interval (in seconds).
2692 uptime System uptime, in seconds.
2694 conky_build_info string
2695 A string containing the build info for this particular instance
2696 of Conky, including the version, build date, and architecture.
2698 conky_build_date string
2699 A string containing the build date for this particular instance
2702 conky_build_arch string
2703 A string containing the build architecture for this particular
2706 conky_version string
2707 A string containing the version of the current instance of
2711 A string containing the path of the current Conky configuration
2714 cairo_text_extents_t:create() function
2715 Call this function to return a new cairo_text_extents_t struc-
2716 ture. A creation function for this structure is not provided by
2717 the cairo API. After calling this, you should use tolua.takeown-
2718 ership() on the return value to ensure ownership is passed prop-
2721 cairo_font_extents_t:create() function
2722 Call this function to return a new cairo_font_extents_t struc-
2723 ture. A creation function for this structure is not provided by
2724 the cairo API. After calling this, you should use tolua.takeown-
2725 ership() on the return value to ensure ownership is passed prop-
2728 cairo_matrix_t:create() function
2729 Call this function to return a new cairo_matrix_t structure. A
2730 creation function for this structure is not provided by the
2731 cairo API. After calling this, you should use tolua.takeowner-
2732 ship() on the return value to ensure ownership is passed proper-
2736 conky -t '${time %D %H:%M}' -o -u 30
2737 Start Conky in its own window with date and clock as text and 30
2738 sec update interval.
2740 conky -a top_left -x 5 -y 500 -d
2741 Start Conky to background at coordinates (5, 500).
2743 conky -C > ~/.conkyrc
2744 Do not start Conky, but have it output the builtin default con-
2745 fig file to ~/.conkyrc for later customising.
2748 ${sysconfdir}/conky/conky.conf
2749 Default system-wide configuration file. The value of
2750 ${sysconfdir} depends on the compile-time options (most likely
2754 Default personal configuration file.
2757 Drawing to root or some other desktop window directly doesn't work with
2758 all window managers. Especially doesn't work well with Gnome and it has
2759 been reported that it doesn't work with KDE either. Nautilus can be
2760 disabled from drawing to desktop with program gconf-editor. Uncheck
2761 show_desktop in /apps/nautilus/preferences/. There is -w switch in
2762 Conky to set some specific window id. You might find xwininfo -tree
2763 useful to find the window to draw to. You can also use -o argument
2764 which makes Conky to create its own window. If you do try running Conky
2765 in its own window, be sure to read up on the own_window_type settings
2769 \9f¨http://conky.sourceforge.net/
\9f©
2771 \9f¨http://www.sourceforge.net/projects/conky
\9f©
2773 \9f¨http://wiki.conky.be
\9f©
2775 #conky on irc.freenode.net
2778 Copyright (c) 2005-2010 Brenden Matthews, Philip Kovacs, et. al. Any
2779 original torsmo code is licensed under the BSD license (see LICENSE.BSD
2780 for a copy). All code written since the fork of torsmo is licensed un-
2781 der the GPL (see LICENSE.GPL for a copy), except where noted different-
2782 ly (such as in portmon code, timed thread code, and audacious code
2783 which are LGPL, and prss which is an MIT-style license).
2786 The Conky dev team (see AUTHORS for a full list of contributors).