1conky(1) conky(1)
2
6 conky - A system monitor for X originally based on the torsmo code, but
7 more kickass. It just keeps on given'er. Yeah.
8
10 conky [ options ]
11
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‐
19 grams.
20 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.
28 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.
33 Thanks for your interest in Conky.
35
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.
47 Conky has (for some time) been available in the repositories of most
49 popular distributions. Here are some installation instructions for a
50 few:
51 Gentoo users -- Conky is in Gentoo's Portage... simply use "emerge
53 app-admin/conky" for installation.
54 Debian, etc. users -- Conky should be in your repositories, and can be
56 installed by doing "aptitude install conky".
57 Example to compile and run Conky with all optional components (note
59 that some configure options may differ for your system):
60 sh autogen.sh # Only required if building from the git repo
62 ./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
69 make
71 make install # Optional
73 src/conky
75 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
78 with other compilers.
79
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.
83 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.
87
89 Command line options override configurations defined in configuration
90 file.
91 -v | -V | --version
93 Prints version and exits
94 -q | --quiet
97 Run Conky in 'quiet mode' (ie. no output)
98 -D | --debug
101 Increase debugging output, ie. -DD for more debugging
102 -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.
108 -b | --double-buffer
111 Use double buffering (eliminates "flicker")
112 -c | --config= FILE
115 Config file to load instead of $HOME/.conkyrc
116 -C | --print-config
119 Print builtin default config to stdout. See also the section EX‐
120 AMPLES for more information.
121 -d | --daemonize
124 Daemonize Conky, aka fork to background
125 -f | --font= FONT
128 Font to use
129 -h | --help
132 Prints command line help and exits
133 -o | --own-window
136 Create own window to draw
137 -t | --text= TEXT
140 Text to render, remember single quotes, like -t ' $uptime '
141 -p | --pause= SECONDS
144 Time to pause before actually starting Conky
145 -u | --interval= SECONDS
148 Update interval
149 -w | --window-id= WIN_ID
152 Window id to draw
153 -X | --display= DISPLAY
156 X11 display to use
157 -x X_COORDINATE
160 X position
161 -y Y_COORDINATE
164 Y position
165 -i COUNT
168 Number of times to update Conky (and quit)
169
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).
175 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/
178 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
182 dzen2.
183 alignment
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.
190 append_file
193 Append the file given as argument.
194 background
197 Boolean value, if true, Conky will be forked to background when
198 started.
199 border_inner_margin
202 Inner border margin in pixels (the margin between the border and
203 text).
204 border_outer_margin
207 Outer border margin in pixels (the margin between the border and
208 the edge of the window).
209 border_width
212 Border width in pixels.
213 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 (#).
218 cpu_avg_samples
221 The number of samples to average for CPU monitoring.
222 default_bar_size
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.
228 default_color
231 Default color and border color
232 default_gauge_size
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
238 default_graph_size
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
244 default_outline_color
247 Default outline color
248 default_shade_color
251 Default shading color and border's shading color
252 disable_auto_reload
255 Enable to disable the inotify-based auto config reload feature.
256 diskio_avg_samples
259 The number of samples to average for disk I/O monitoring.
260 display
263 Specify an X display to connect to.
264 double_buffer
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
269 so big.
270 draw_borders
273 Draw borders around text?
274 draw_graph_borders
277 Draw borders around graphs?
278 draw_outline
281 Draw outlines?
282 draw_shades
285 Draw shades?
286 extra_newline
289 Put an extra newline at the end when writing to stdout, useful
290 for writing to awesome's wiboxes.
291 font Font name in X, xfontsel can be used to get a nice font
294 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.
300 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'.
305 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'.
310 hddtemp_host
313 Hostname to connect to for hddtemp objects. Defaults to
314 "127.0.0.1".
315 hddtemp_port
318 Port to use for hddtemp connections. Defaults to 7634.
319 if_up_strictness
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.
326 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.
334 imlib_cache_flush_interval
337 Interval (in seconds) to flush Imlib2 cache.
338 imlib_cache_size
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
343 cache.
344 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.
353 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.
362 lua_load
365 Loads the Lua scripts separated by spaces.
366 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.
375 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.
383 mail_spool
386 Mail spool for mail checking
387 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)
392 max_specials
395 Maximum number of special things, e.g. fonts, offsets, aligns,
396 etc. (default is 512)
397 max_text_width width
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
403 max_user_text bytes
406 Maximum size of user text buffer, i.e. layout below TEXT line in
407 config file (default is 16384 bytes)
408 maximum_width pixels
411 Maximum width of window
412 minimum_size width (height)
415 Minimum size of window
416 mpd_host
419 Host of MPD server
420 mpd_password
423 MPD server password
424 mpd_port
427 Port of MPD server
428 music_player_interval
431 Music player thread update interval (defaults to Conky's update
432 interval)
433 net_avg_samples
436 The number of samples to average for net data
437 no_buffers
440 Subtract (file system) buffers from used memory?
441 nvidia_display
444 The display that the nvidia variable will use (defaults to the
445 value of the display variable)
446 out_to_console
449 Print text to stdout.
450 out_to_ncurses
453 Print text in the console, but use ncurses so that conky can
454 print the text of a new update over the old text. (In the future
455 this will provide more useful things)
456 out_to_stderr
459 Print text to stderr.
460 out_to_x
463 When set to no, there will be no output in X (useful when you
464 also use things like out_to_console). If you set it to no, make
465 sure that it's placed before all other X-related setting (take
466 the first line of your configfile to be sure). Default value is
467 yes
468 override_utf8_locale
471 Force UTF8? requires XFT
472 overwrite_file
475 Overwrite the file given as argument.
476 own_window
479 Boolean, create own window to draw?
480 own_window_class
483 Manually set the WM_CLASS name. Defaults to "Conky".
484 own_window_colour colour
487 If own_window_transparent no, set a specified background colour
488 (defaults to black). Takes either a hex value (e.g. ffffff, note
489 the lack of '#') or a valid RGB name (see /usr/lib/X11/rgb.txt)
490 own_window_hints undecorated,below,above,sticky,skip_taskbar,skip_pager
493 If own_window is yes, you may use these window manager hints to
494 affect the way Conky displays. Notes: Use own_window_type desk‐
495 top as another way to implement many of these hints implicitly.
496 If you use own_window_type override, window manager hints have
497 no meaning and are ignored.
498 own_window_title
501 Manually set the window name. Defaults to "<hostname> - conky".
502 own_window_argb_visual
505 Boolean, use ARGB visual? ARGB can be used for real transparen‐
506 cy, note that a composite manager is required for real trans‐
507 parency. This option will not work as desired (in most cases) in
508 conjunction with 'own_window_type override'.
509 own_window_argb_value
512 When ARGB visuals are enabled, this use this to modify the alpha
513 value used. Valid range is 0-255, where 0 is 0% opacity, and 255
514 is 100% opacity.
515 own_window_transparent
518 Boolean, set transparency? If ARGB visual is enabled, sets back‐
519 ground opacity to 0%.
520 own_window_type
523 if own_window is yes, you may specify type normal, desktop,
524 dock, panel or override (default: normal). Desktop windows are
525 special windows that have no window decorations; are always vis‐
526 ible on your desktop; do not appear in your pager or taskbar;
527 and are sticky across all workspaces. Panel windows reserve
528 space along a desktop edge, just like panels and taskbars, pre‐
529 venting maximized windows from overlapping them. The edge is
530 chosen based on the alignment option. Override windows are not
531 under the control of the window manager. Hints are ignored. This
532 type of window can be useful for certain situations.
533 pad_percents
536 Pad percentages to this many decimals (0 = no padding)
537 pop3 Default global POP3 server. Arguments are: "host user pass [-i
540 interval (in seconds)] [-p port] [-e 'command'] [-r retries]".
541 Default port is 110, default interval is 5 minutes, and default
542 number of retries before giving up is 5. If the password is sup‐
543 plied as '*', you will be prompted to enter the password when
544 Conky starts.
545 short_units
548 Shortens units to a single character (kiB->k, GiB->G, etc.). De‐
549 fault is off.
550 show_graph_range
553 Shows the time range covered by a graph.
554 show_graph_scale
557 Shows the maximum value in scaled graphs.
558 stippled_borders
561 Border stippling (dashing) in pixels
562 temperature_unit
565 Desired output unit of all objects displaying a temperature. Pa‐
566 rameters are either "fahrenheit" or "celsius". The default unit
567 is degree Celsius.
568 templateN
571 Define a template for later use inside TEXT segments. Substitute
572 N by a digit between 0 and 9, inclusively. The value of the
573 variable is being inserted into the stuff below TEXT at the cor‐
574 responding position, but before some substitutions are applied:
575 '\n' -> newline
577 '\\' -> backslash
578 '\ ' -> space
579 '\N' -> template argument N
580 text_buffer_size bytes
583 Size of the standard text buffer (default is 256 bytes). This
584 buffer is used for intermediary text, such as individual lines,
585 output from $exec vars, and various other variables. Increasing
586 the size of this buffer can drastically reduce Conky's perfor‐
587 mance, but will allow for more text display per variable. The
588 size of this buffer cannot be smaller than the default value of
589 256 bytes.
590 times_in_seconds
593 If true, variables that output times output a number that repre‐
594 sents seconds. This doesn't affect $time, $tztime and $utime
595 top_cpu_separate
598 If true, cpu in top will show usage of one processor's power. If
599 false, cpu in top will show the usage of all processors' power
600 combined.
601 top_name_width
604 Width for $top name value (defaults to 15 characters).
605 total_run_times
608 Total number of times for Conky to update before quitting. Zero
609 makes Conky run forever
610 update_interval seconds
613 Update interval
614 update_interval_on_battery seconds
617 Update interval when running on batterypower
618 uppercase
621 Boolean value, if true, text is rendered in upper case
622 use_spacer
625 Adds spaces around certain objects to stop them from moving oth‐
626 er things around. Arguments are left, right, and none (default).
627 The old true/false values are deprecated and default to
628 right/none respectively. Note that this only helps if you are
629 using a mono font, such as Bitstream Vera Sans Mono.
630 use_xft
633 Use Xft (anti-aliased font and stuff)
634 xftalpha
637 Alpha of Xft font. Must be a value at or between 1 and 0.
638 xftfont
641 Xft font to use.
642
645 Colours are parsed using XParsecolor(), there might be a list of them:
646 /usr/share/X11/rgb.txt. Colour can be also in #rrggbb format (hex).
647 Some objects may create threads, and sometimes these threads will not
649 be destroyed until Conky terminates. There is no way to destroy or
650 clean up threads while Conky is running. For example, if you use an MPD
651 variable, the MPD thread will keep running until Conky dies. Some
652 threaded objects will use one of the parameters as a 'key', so that you
653 only have 1 relevant thread running (for example, the $curl, $rss and
654 $weather objects launch one thread per URI).
655 acpiacadapter (adapter)
657 ACPI ac adapter state. On linux, the adapter option specifies
658 the subfolder of /sys/class/power_supply containing the state
659 information (tries "AC" and "ADP1" if there is no argument giv‐
660 en). Non-linux systems ignore it.
661 acpifan
664 ACPI fan state
665 acpitemp
668 ACPI temperature in C.
669 addr (interface)
672 IP address for an interface, or "No Address" if no address is
673 assigned.
674 addrs (interface)
677 IP addresses for an interface (if one - works like addr). Linux
678 only.
679 adt746xcpu
682 CPU temperature from therm_adt746x
683 adt746xfan
686 Fan speed from therm_adt746x
687 alignc (num)
690 Align text to centre
691 alignr (num)
694 Right-justify text, with space of N
695 apcupsd host port
698 Sets up the connection to apcupsd daemon. Prints nothing, de‐
699 faults to localhost:3551
700 apcupsd_cable
703 Prints the UPS connection type.
704 apcupsd_charge
707 Current battery capacity in percent.
708 apcupsd_lastxfer
711 Reason for last transfer from line to battery.
712 apcupsd_linev
715 Nominal input voltage.
716 apcupsd_load
719 Current load in percent.
720 apcupsd_loadbar
723 Bar showing current load.
724 apcupsd_loadgauge (height),(width)
727 Gauge that shows current load.
728 apcupsd_loadgraph (height),(width) (gradient colour 1) (gradient colour
731 2) (scale) (-t) (-l)
732 History graph of current load.
733 apcupsd_model
736 Prints the model of the UPS.
737 apcupsd_name
740 Prints the UPS user-defined name.
741 apcupsd_status
744 Prints current status (on-line, on-battery).
745 apcupsd_temp
748 Current internal temperature.
749 apcupsd_timeleft
752 Time left to run on battery.
753 apcupsd_upsmode
756 Prints the UPS mode (e.g. standalone).
757 apm_adapter
760 Display APM AC adapter status (FreeBSD only)
761 apm_battery_life
764 Display APM battery life in percent (FreeBSD only)
765 apm_battery_time
768 Display remaining APM battery life in hh:mm:ss or "unknown" if
769 AC adapterstatus is on-line or charging (FreeBSD only)
770 audacious_bar (height),(width)
773 Progress bar
774 audacious_bitrate
777 Bitrate of current tune
778 audacious_channels
781 Number of audio channels of current tune
782 audacious_filename
785 Full path and filename of current tune
786 audacious_frequency
789 Sampling frequency of current tune
790 audacious_length
793 Total length of current tune as MM:SS
794 audacious_length_seconds
797 Total length of current tune in seconds
798 audacious_main_volume
801 The current volume fetched from Audacious
802 audacious_playlist_length
805 Number of tunes in playlist
806 audacious_playlist_position
809 Playlist position of current tune
810 audacious_position
813 Position of current tune (MM:SS)
814 audacious_position_seconds
817 Position of current tune in seconds
818 audacious_status
821 Player status (Playing/Paused/Stopped/Not running)
822 audacious_title (max length)
825 Title of current tune with optional maximum length specifier
826 battery (num)
829 Battery status and remaining percentage capacity of ACPI or APM
830 battery. ACPI battery number can be given as argument (default
831 is BAT0).
832 battery_bar (height),(width) (num)
835 Battery percentage remaining of ACPI battery in a bar. ACPI bat‐
836 tery number can be given as argument (default is BAT0).
837 battery_percent (num)
840 Battery percentage remaining for ACPI battery. ACPI battery
841 number can be given as argument (default is BAT0).
842 battery_short (num)
845 Battery status and remaining percentage capacity of ACPI or APM
846 battery. ACPI battery number can be given as argument (default
847 is BAT0). This mode display a short status, which means that C
848 is displayed instead of charging, D for discharging, F for full,
849 N for not present, E for empty and U for unknown.
850 battery_time (num)
853 Battery charge/discharge time remaining of ACPI battery. ACPI
854 battery number can be given as argument (default is BAT0).
855 blink text_and_other_conky_vars
858 Let 'text_and_other_conky_vars' blink on and off.
859 bmpx_album
862 Album in current BMPx track
863 bmpx_artist
866 Artist in current BMPx track
867 bmpx_bitrate
870 Bitrate of the current BMPx track
871 bmpx_title
874 Title of the current BMPx track
875 bmpx_track
878 Track number of the current BMPx track
879 bmpx_uri
882 URI of the current BMPx track
883 buffers
886 Amount of memory buffered
887 cached Amount of memory cached
890 cmdline_to_pid string
893 PID of the first process that has string in it's commandline
894 color (color)
897 Change drawing color to 'color' which is a name of a color or a
898 hexcode preceded with # (for example #0A1B2C ). If you use
899 ncurses only the following colors are supported: red,green,yel‐
900 low,blue,magenta,cyan,black,white.
901 colorN Change drawing color to colorN configuration option, where N is
904 a digit between 0 and 9, inclusively.
905 combine var1 var2
908 Places the lines of var2 to the right of the lines of var1 sepa‐
909 rated by the chars that are put between var1 and var2. For exam‐
910 ple: ${combine ${head /proc/cpuinfo 2} - ${head /proc/meminfo
911 1}} gives as output "cpuinfo_line1 - meminfo_line1" on line 1
912 and "cpuinfo_line2 -" on line 2. $combine vars can also be nest‐
913 ed to place more vars next to each other.
914 conky_build_arch
917 CPU architecture Conky was built for
918 conky_build_date
921 Date Conky was built
922 conky_version
925 Conky version
926 cpu (cpuN)
929 CPU usage in percents. For SMP machines, the CPU number can be
930 provided as an argument. ${cpu cpu0} is the total usage, and
931 ${cpu cpuX} (X >= 1) are individual CPUs.
932 cpubar (cpuN) (height),(width)
935 Bar that shows CPU usage, height is bar's height in pixels. See
936 $cpu for more info on SMP.
937 cpugauge (cpuN) (height),(width)
940 Elliptical gauge that shows CPU usage, height and width are
941 gauge's vertical and horizontal axis respectively. See $cpu for
942 more info on SMP.
943 cpugraph (cpuN) (height),(width) (gradient colour 1) (gradient colour
946 2) (scale) (-t) (-l)
947 CPU usage graph, with optional colours in hex, minus the #. See
948 $cpu for more info on SMP. Uses a logarithmic scale (to see
949 small numbers) when you use the -l switch. Takes the switch '-t'
950 to use a temperature gradient, which makes the gradient values
951 change depending on the amplitude of a particular graph value
952 (try it and see).
953 curl url (interval_in_minutes)
956 Download data from URI using Curl at the specified interval. The
957 interval may be a floating point value greater than 0, otherwise
958 defaults to 15 minutes. Most useful when used in conjunction
959 with Lua and the Lua API. This object is threaded, and once a
960 thread is created it can't be explicitly destroyed. One thread
961 will run for each URI specified. You can use any protocol that
962 Curl supports.
963 desktop
965 Number of the desktop on which conky is running or the message
966 "Not running in X" if this is the case.
967 desktop_name
970 Name of the desktop on which conky is running or the message
971 "Not running in X" if this is the case.
972 desktop_number
975 Number of desktops or the message "Not running in X" if this is
976 the case.
977 disk_protect device
980 Disk protection status, if supported (needs kernel-patch).
981 Prints either "frozen" or "free " (note the padding).
982 diskio (device)
985 Displays current disk IO. Device is optional, and takes the form
986 of sda for /dev/sda. Individual partitions are allowed.
987 diskio_read (device)
990 Displays current disk IO for reads. Device as in diskio.
991 diskio_write (device)
994 Displays current disk IO for writes. Device as in diskio.
995 diskiograph (device) (height),(width) (gradient colour 1) (gradient
998 colour 2) (scale) (-t) (-l)
999 Disk IO graph, colours defined in hex, minus the #. If scale is
1000 non-zero, it becomes the scale for the graph. Uses a logarithmic
1001 scale (to see small numbers) when you use -l switch. Takes the
1002 switch '-t' to use a temperature gradient, which makes the gra‐
1003 dient values change depending on the amplitude of a particular
1004 graph value (try it and see).
1005 diskiograph_read (device) (height),(width) (gradient colour 1) (gradi‐
1008 ent colour 2) (scale) (-t) (-l)
1009 Disk IO graph for reads, colours defined in hex, minus the #. If
1010 scale is non-zero, it becomes the scale for the graph. Device as
1011 in diskio. Uses a logarithmic scale (to see small numbers) when
1012 you use -l switch. Takes the switch '-t' to use a temperature
1013 gradient, which makes the gradient values change depending on
1014 the amplitude of a particular graph value (try it and see).
1015 diskiograph_write (device) (height),(width) (gradient colour 1) (gradi‐
1018 ent colour 2) (scale) (-t) (-l)
1019 Disk IO graph for writes, colours defined in hex, minus the #.
1020 If scale is non-zero, it becomes the scale for the graph. Device
1021 as in diskio. Uses a logarithmic scale (to see small numbers)
1022 when you use -l switch. Takes the switch '-t' to use a tempera‐
1023 ture gradient, which makes the gradient values change depending
1024 on the amplitude of a particular graph value (try it and see).
1025 downspeed (net)
1028 Download speed in suitable IEC units
1029 downspeedf (net)
1032 Download speed in KiB with one decimal
1033 downspeedgraph (netdev) (height),(width) (gradient colour 1) (gradient
1036 colour 2) (scale) (-t) (-l)
1037 Download speed graph, colours defined in hex, minus the #. If
1038 scale is non-zero, it becomes the scale for the graph. Uses a
1039 logarithmic scale (to see small numbers) when you use -l switch.
1040 Takes the switch '-t' to use a temperature gradient, which makes
1041 the gradient values change depending on the amplitude of a par‐
1042 ticular graph value (try it and see).
1043 draft_mails (maildir) (interval)
1046 Number of mails marked as draft in the specified mailbox or mail
1047 spool if not. Only maildir type mailboxes are supported, mbox
1048 type will return -1.
1049 else Text to show if any of the above are not true
1052 endif Ends an $if block.
1055 entropy_avail
1058 Current entropy available for crypto freaks
1059 entropy_bar (height),(width)
1062 Normalized bar of available entropy for crypto freaks
1063 entropy_perc
1066 Percentage of entropy available in comparison to the poolsize
1067 entropy_poolsize
1070 Total size of system entropy pool for crypto freaks
1071 eval string
1074 Evaluates given string according to the rules of TEXT interpre‐
1075 tation, i.e. parsing any contained text object specifications
1076 into their output, any occuring '$$' into a single '$' and so
1077 on. The output is then being parsed again.
1078 eve api_userid api_key character_id
1081 Fetches your currently training skill from the Eve Online API
1082 servers (http://www.eve-online.com/) and displays the skill
1083 along with the remaining training time.
1084 exec command
1087 Executes a shell command and displays the output in conky. warn‐
1088 ing: this takes a lot more resources than other variables. I'd
1089 recommend coding wanted behaviour in C and posting a patch.
1090 execbar command
1093 Same as exec, except if the first value return is a value be‐
1094 tween 0-100, it will use that number for a bar. The size for
1095 bars can be controlled via the default_bar_size config setting.
1096 execgauge command
1099 Same as exec, except if the first value returned is a value be‐
1100 tween 0-100, it will use that number for a gauge. The size for
1101 gauges can be controlled via the default_gauge_size config set‐
1102 ting.
1103 execgraph (-t) (-l) command
1106 Same as execbar, but graphs values. Uses a logaritmic scale when
1107 the log option (-l switch) is given (to see small numbers). Val‐
1108 ues still have to be between 0 and 100. The size for graphs can
1109 be controlled via the default_graph_size config setting. Takes
1110 the switch '-t' to use a temperature gradient, which makes the
1111 gradient values change depending on the amplitude of a particu‐
1112 lar graph value (try it and see). If -t or -l is your first ar‐
1113 gument, you may need to preceed it by a space (' '). You may al‐
1114 so use double-quotes around the exec argument should you need to
1115 execute a command with spaces. For example, ${execgraph "date
1116 +'%S'"} to execute `date +'%S'` and graph the result. Without
1117 quotes, it would simply print the result of `date`.
1118 execi interval command
1121 Same as exec but with specific interval. Interval can't be less
1122 than update_interval in configuration. See also $texeci
1123 execibar interval command
1126 Same as execbar, except with an interval
1127 execigauge interval command
1130 Same as execgauge, but takes an interval arg and gauges values.
1131 execigraph interval (-t) (-l) command
1134 Same as execgraph, but takes an interval arg and graphs values.
1135 If -t or -l is your first argument, you may need to preceed it
1136 by a space (' ').
1137 execp command
1140 Executes a shell command and displays the output in conky. warn‐
1141 ing: this takes a lot more resources than other variables. I'd
1142 recommend coding wanted behaviour in C and posting a patch. This
1143 differs from $exec in that it parses the output of the command,
1144 so you can insert things like ${color red}hi!${color} in your
1145 script and have it correctly parsed by Conky. Caveats: Conky
1146 parses and evaluates the output of $execp every time Conky
1147 loops, and then destroys all the objects. If you try to use any‐
1148 thing like $execi within an $execp statement, it will function‐
1149 ally run at the same interval that the $execp statement runs, as
1150 it is created and destroyed at every interval.
1151 execpi interval command
1154 Same as execp but with specific interval. Interval can't be
1155 less than update_interval in configuration. Note that the output
1156 from the $execpi command is still parsed and evaluated at every
1157 interval.
1158 flagged_mails (maildir) (interval)
1161 Number of mails marked as flagged in the specified mailbox or
1162 mail spool if not. Only maildir type mailboxes are supported,
1163 mbox type will return -1.
1164 font (font)
1167 Specify a different font. This new font will apply to the cur‐
1168 rent line and everything following. You can use a $font with no
1169 arguments to change back to the default font (much like with
1170 $color)
1171 format_time seconds format
1174 Format time given in seconds. This var only works when the
1175 times_in_seconds configuration setting is on. Format is a string
1176 that should start and end with a "-char. The "-chars are not
1177 part of the output, \w,\d,\h,\m,\s,\(,\) and \\ are replaced by
1178 weeks,days,hours,minutes,seconds,(,) and \. If you leave out a
1179 unit, it's value will be expressed in the highest unite lower
1180 then the one left out. Text between ()-chars will not be visible
1181 if a replaced unit in this text is 0. If seconds is a decimal
1182 number then you can see the numbers behind the point by using \S
1183 followed by a number that specifies the amount of digits behind
1184 the point that you want to see (maximum 9). You can also place
1185 a 'x' behind \S so you have all digits behind the point and no
1186 trailing zero's. (also maximum 9)
1187 forwarded_mails (maildir) (interval)
1190 Number of mails marked as forwarded in the specified mailbox or
1191 mail spool if not. Only maildir type mailboxes are supported,
1192 mbox type will return -1.
1193 freq (n)
1196 Returns CPU #n's frequency in MHz. CPUs are counted from 1. If
1197 omitted, the parameter defaults to 1.
1198 freq_g (n)
1201 Returns CPU #n's frequency in GHz. CPUs are counted from 1. If
1202 omitted, the parameter defaults to 1.
1203 fs_bar (height),(width) fs
1206 Bar that shows how much space is used on a file system. height
1207 is the height in pixels. fs is any file on that file system.
1208 fs_bar_free (height),(width) fs
1211 Bar that shows how much space is free on a file system. height
1212 is the height in pixels. fs is any file on that file system.
1213 fs_free (fs)
1216 Free space on a file system available for users.
1217 fs_free_perc (fs)
1220 Free percentage of space on a file system available for users.
1221 fs_size (fs)
1224 File system size.
1225 fs_type (fs)
1228 File system type.
1229 fs_used (fs)
1232 File system used space.
1233 fs_used_perc (fs)
1236 Percent of file system used space.
1237 goto x The next element will be printed at position 'x'.
1240 gw_iface
1243 Displays the default route's interface or "multiple"/"none" ac‐
1244 cordingly.
1245 gw_ip Displays the default gateway's IP or "multiple"/"none" accord‐
1248 ingly.
1249 hddtemp (dev)
1252 Displays temperature of a selected hard disk drive as reported
1253 by the hddtemp daemon. Use hddtemp_host and hddtemp_port to
1254 specify a host and port for all hddtemp objects. If no dev pa‐
1255 rameter is given, the first disk returned by the hddtemp daemon
1256 is used.
1257 head logfile lines (next_check)
1260 Displays first N lines of supplied text file. The file is
1261 checked every 'next_check' update. If next_check is not sup‐
1262 plied, Conky defaults to 2. Max of 30 lines can be displayed, or
1263 until the text buffer is filled.
1264 hr (height)
1267 Horizontal line, height is the height in pixels
1268 hwmon (dev) type n (factor offset)
1271 Hwmon sensor from sysfs (Linux 2.6). Parameter dev may be omit‐
1272 ted if you have only one hwmon device. Parameter type is either
1273 'in' or 'vol' meaning voltage; 'fan' meaning fan; 'temp' meaning
1274 temperature. Parameter n is number of the sensor. See
1275 /sys/class/hwmon/ on your local computer. The optional arguments
1276 'factor' and 'offset' allow precalculation of the raw input,
1277 which is being modified as follows: 'input = input * factor +
1278 offset'. Note that they have to be given as decimal values (i.e.
1279 contain at least one decimal place).
1280 i2c (dev) type n (factor offset)
1283 I2C sensor from sysfs (Linux 2.6). Parameter dev may be omitted
1284 if you have only one I2C device. Parameter type is either 'in'
1285 or 'vol' meaning voltage; 'fan' meaning fan; 'temp' meaning tem‐
1286 perature. Parameter n is number of the sensor. See
1287 /sys/bus/i2c/devices/ on your local computer. The optional argu‐
1288 ments 'factor' and 'offset' allow precalculation of the raw in‐
1289 put, which is being modified as follows: 'input = input * factor
1290 + offset'. Note that they have to be given as decimal values
1291 (i.e. contain at least one decimal place).
1292 i8k_ac_status
1295 If running the i8k kernel driver for Inspiron laptops, displays
1296 whether ac power is on, as listed in /proc/i8k (translated to
1297 human-readable). Beware that this is by default not enabled by
1298 i8k itself.
1299 i8k_bios
1302 If running the i8k kernel driver for Inspiron laptops, displays
1303 the bios version as listed in /proc/i8k.
1304 i8k_buttons_status
1307 If running the i8k kernel driver for Inspiron laptops, displays
1308 the volume buttons status as listed in /proc/i8k.
1309 i8k_cpu_temp
1312 If running the i8k kernel driver for Inspiron laptops, displays
1313 the cpu temperature in Celsius, as reported by /proc/i8k.
1314 i8k_left_fan_rpm
1317 If running the i8k kernel driver for Inspiron laptops, displays
1318 the left fan's rate of rotation, in revolutions per minute as
1319 listed in /proc/i8k. Beware, some laptops i8k reports these fans
1320 in reverse order.
1321 i8k_left_fan_status
1324 If running the i8k kernel driver for Inspiron laptops, displays
1325 the left fan status as listed in /proc/i8k (translated to human-
1326 readable). Beware, some laptops i8k reports these fans in re‐
1327 verse order.
1328 i8k_right_fan_rpm
1331 If running the i8k kernel driver for Inspiron laptops, displays
1332 the right fan's rate of rotation, in revolutions per minute as
1333 listed in /proc/i8k. Beware, some laptops i8k reports these fans
1334 in reverse order.
1335 i8k_right_fan_status
1338 If running the i8k kernel driver for Inspiron laptops, displays
1339 the right fan status as listed in /proc/i8k (translated to hu‐
1340 man-readable). Beware, some laptops i8k reports these fans in
1341 reverse order.
1342 i8k_serial
1345 If running the i8k kernel driver for Inspiron laptops, displays
1346 your laptop serial number as listed in /proc/i8k.
1347 i8k_version
1350 If running the i8k kernel driver for Inspiron laptops, displays
1351 the version formatting of /proc/i8k.
1352 ibm_brightness
1355 If running the IBM ACPI, displays the brigtness of the laptops's
1356 LCD (0-7).
1357 ibm_fan
1360 If running the IBM ACPI, displays the fan speed.
1361 ibm_temps N
1364 If running the IBM ACPI, displays the temperatures from the IBM
1365 temperature sensors (N=0..7) Sensor 0 is on the CPU, 3 is on the
1366 GPU.
1367 ibm_volume
1370 If running the IBM ACPI, displays the "master" volume, con‐
1371 trolled by the volume keys (0-14).
1372 iconv_start codeset_from codeset_to
1375 Convert text from one codeset to another using GNU iconv. Needs
1376 to be stopped with iconv_stop.
1377 iconv_stop
1380 Stop iconv codeset conversion.
1381 if_empty (var)
1384 if conky variable VAR is empty, display everything between
1385 $if_empty and the matching $endif
1386 if_existing file (string)
1389 if FILE exists, display everything between if_existing and the
1390 matching $endif. The optional second paramater checks for FILE
1391 containing the specified string and prints everything between
1392 $if_existing and the matching $endif.
1393 if_gw if there is at least one default gateway, display everything be‐
1396 tween $if_gw and the matching $endif
1397 if_match expression
1400 Evaluates the given boolean expression, printing everything be‐
1401 tween $if_match and the matching $endif depending on whether the
1402 evaluation returns true or not. Valid expressions consist of a
1403 left side, an operator and a right side. Left and right sides
1404 are being parsed for contained text objects before evaluation.
1405 Recognised left and right side types are:
1406 doubleArgument consists of only digits and a single dot.
1408 longArgument consists of only digits.
1409 stringArgument is enclosed in quotation marks (")
1410 Valid operands are: '>', '<', '>=', '<=', '==', '!='.
1412 if_mixer_mute (mixer)
1415 If mixer exists, display everything between $if_mixer_mute and
1416 the matching $endif. If no mixer is specified, "Master" is used.
1417 if_mounted (mountpoint)
1420 if MOUNTPOINT is mounted, display everything between $if_mounted
1421 and the matching $endif
1422 if_mpd_playing
1425 if mpd is playing or paused, display everything between
1426 $if_mpd_playing and the matching $endif
1427 if_running (process)
1430 if PROCESS is running, display everything $if_running and the
1431 matching $endif. This uses the ``pidof'' command, so the -x
1432 switch is also supported.
1433 if_smapi_bat_installed (INDEX)
1436 when using smapi, if the battery with index INDEX is installed,
1437 display everything between $if_smapi_bat_installed and the
1438 matching $endif
1439 if_up (interface)
1442 if INTERFACE exists and is up, display everything between $if_up
1443 and the matching $endif
1444 if_updatenr (updatenr)
1447 If it's the UPDATENR-th time that conky updates, display every‐
1448 thing between $if_updatenr and the matching $endif. The counter
1449 resets when the highest UPDATENR is reached. Example : "{$if_up‐
1450 datenr 1}foo$endif{$if_updatenr 2}bar$endif{$if_updatenr 4}$en‐
1451 dif" shows foo 25% of the time followed by bar 25% of the time
1452 followed by nothing the other half of the time.
1453 if_xmms2_connected
1456 Display everything between $if_xmms2_connected and the matching
1457 $endif if xmms2 is running.
1458 image <path to image> (-p x,y) (-s WxH) (-n) (-f interval)
1461 Renders an image from the path specified using Imlib2. Takes 4
1462 optional arguments: a position, a size, a no-cache switch, and a
1463 cache flush interval. Changing the x,y position will move the
1464 position of the image, and changing the WxH will scale the im‐
1465 age. If you specify the no-cache flag (-n), the image will not
1466 be cached. Alternately, you can specify the -f int switch to
1467 specify a cache flust interval for a particular image. Example:
1468 ${image /home/brenden/cheeseburger.jpg -p 20,20 -s 200x200} will
1469 render 'cheeseburger.jpg' at (20,20) scaled to 200x200 pixels.
1470 Conky does not make any attempt to adjust the position (or any
1471 other formatting) of images, they are just rendered as per the
1472 arguments passed. The only reason $image is part of the TEXT
1473 section, is to allow for runtime modifications, through $execp
1474 $lua_parse, or some other method.
1475 imap_messages (args)
1478 Displays the number of messages in your global IMAP inbox by de‐
1479 fault. You can define individual IMAP inboxes separately by
1480 passing arguments to this object. Arguments are: "host user
1481 pass [-i interval (in seconds)] [-f 'folder'] [-p port] [-e
1482 'command'] [-r retries]". Default port is 143, default folder is
1483 'INBOX', default interval is 5 minutes, and default number of
1484 retries before giving up is 5. If the password is supplied as
1485 '*', you will be prompted to enter the password when Conky
1486 starts.
1487 imap_unseen (args)
1490 Displays the number of unseen messages in your global IMAP inbox
1491 by default. You can define individual IMAP inboxes separately by
1492 passing arguments to this object. Arguments are: "host user pass
1493 [-i interval (in seconds)] [-f 'folder'] [-p port] [-e 'com‐
1494 mand'] [-r retries]". Default port is 143, default folder is
1495 'INBOX', default interval is 5 minutes, and default number of
1496 retries before giving up is 5. If the password is supplied as
1497 '*', you will be prompted to enter the password when Conky
1498 starts.
1499 include path
1502 Loads the configfile at path, places the configsettings behind
1503 the configsettings in the orginal config and places the vars
1504 where the includevar stood.
1505 ioscheduler disk
1507 Prints the current ioscheduler used for the given disk name
1508 (i.e. e.g. "hda" or "sdb")
1509 kernel Kernel version
1512 laptop_mode
1515 The value of /proc/sys/vm/laptop_mode
1516 lines textfile
1519 Displays the number of lines in the given file
1520 loadavg (1|2|3)
1523 System load average, 1 is for past 1 minute, 2 for past 5 min‐
1524 utes and 3 for past 15 minutes. Without argument, prints all
1525 three values separated by whitespace.
1526 loadgraph (height),(width) (gradient colour 1) (gradient colour 2)
1529 (scale) (-t) (-l)
1530 Load1 average graph, similar to xload, with optional colours in
1531 hex, minus the #. Uses a logarithmic scale (to see small num‐
1532 bers) when you use the -l switch. Takes the switch '-t' to use
1533 a temperature gradient, which makes the gradient values change
1534 depending on the amplitude of a particular graph value (try it
1535 and see).
1536 lua function_name (function parameters)
1539 Executes a Lua function with given parameters, then prints the
1540 returned string. See also 'lua_load' on how to load scripts.
1541 Conky puts 'conky_' in front of function_name to prevent acci‐
1542 dental calls to the wrong function unless you put you place
1543 'conky_' in front of it yourself.
1544 lua_bar (height, width) function_name (function parameters)
1547 Executes a Lua function with given parameters and draws a bar.
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‐
1552 self.
1553 lua_gauge (height, width) function_name (function parameters)
1556 Executes a Lua function with given parameters and draws a gauge.
1557 Expects result value to be an integer between 0 and 100. See al‐
1558 so 'lua_load' on how to load scripts. Conky puts 'conky_' in
1559 front of function_name to prevent accidental calls to the wrong
1560 function unless you put you place 'conky_' in front of it your‐
1561 self.
1562 lua_graph function_name (height),(width) (gradient colour 1) (gradient
1565 colour 2) (scale) (-t) (-l)
1566 Executes a Lua function with and draws a graph. Expects result
1567 value to be any number, and by default will scale to show the
1568 full range. See also 'lua_load' on how to load scripts. Takes
1569 the switch '-t' to use a temperature gradient, which makes the
1570 gradient values change depending on the amplitude of a particu‐
1571 lar graph value (try it and see). Conky puts 'conky_' in front
1572 of function_name to prevent accidental calls to the wrong func‐
1573 tion unless you put you place 'conky_' in front of it yourself.
1574 lua_parse function_name (function parameters)
1577 Executes a Lua function with given parameters as per $lua, then
1578 parses and prints the result value as per the syntax for Conky's
1579 TEXT section. See also 'lua_load' on how to load scripts. Conky
1580 puts 'conky_' in front of function_name to prevent accidental
1581 calls to the wrong function unless you put you place 'conky_' in
1582 front of it yourself.
1583 machine
1586 Machine, i686 for example
1587 mails (mailbox) (interval)
1590 Mail count in the specified mailbox or your mail spool if not.
1591 Both mbox and maildir type mailboxes are supported. You can use
1592 a program like fetchmail to get mails from some server using
1593 your favourite protocol. See also new_mails.
1594 mboxscan (-n number of messages to print) (-fw from width) (-sw subject
1597 width) mbox
1598 Print a summary of recent messages in an mbox format mailbox.
1599 mbox parameter is the filename of the mailbox (can be encapsu‐
1600 lated using '"', ie. ${mboxscan -n 10 "/home/brenden/some box"}
1601 mem Amount of memory in use
1604 membar (height),(width)
1607 Bar that shows amount of memory in use
1608 memeasyfree
1611 Amount of free memory including the memory that is very easily
1612 freed (buffers/cache)
1613 memfree
1616 Amount of free memory
1617 memgauge (height),(width)
1620 Gauge that shows amount of memory in use (see cpugauge)
1621 memgraph (height),(width) (gradient colour 1) (gradient colour 2)
1624 (scale) (-t) (-l)
1625 Memory usage graph. Uses a logarithmic scale (to see small num‐
1626 bers) when you use the -l switch. Takes the switch '-t' to use a
1627 temperature gradient, which makes the gradient values change de‐
1628 pending on the amplitude of a particular graph value (try it and
1629 see).
1630 memmax Total amount of memory
1633 memperc
1636 Percentage of memory in use
1637 mixer (device)
1640 Prints the mixer value as reported by the OS. Default mixer is
1641 "Master", but you can specify one of the available ALSA Simple
1642 mixer controls. You can find the list of those available on
1643 your system using amixer.
1644 mixerbar (device)
1647 Displays mixer value in a bar as reported by the OS. See docs
1648 for $mixer for details on arguments.
1649 mixerl (device)
1652 Prints the left channel mixer value as reported by the OS. See
1653 docs for $mixer for details on arguments.
1654 mixerlbar (device)
1657 Displays the left channel mixer value in a bar as reported by
1658 the OS. See docs for $mixer for details on arguments.
1659 mixerr (device)
1662 Prints the right channel mixer value as reported by the OS. See
1663 docs for $mixer for details on arguments.
1664 mixerrbar (device)
1667 Displays the right channel mixer value in a bar as reported by
1668 the OS. See docs for $mixer for details on arguments.
1669 moc_album
1672 Album of the current MOC song
1673 moc_artist
1676 Artist of the current MOC song
1677 moc_bitrate
1680 Bitrate in the current MOC song
1681 moc_curtime
1684 Current time of the current MOC song
1685 moc_file
1688 File name of the current MOC song
1689 moc_rate
1692 Rate of the current MOC song
1693 moc_song
1696 The current song name being played in MOC.
1697 moc_state
1700 Current state of MOC; playing, stopped etc.
1701 moc_timeleft
1704 Time left in the current MOC song
1705 moc_title
1708 Title of the current MOC song
1709 moc_totaltime
1712 Total length of the current MOC song
1713 monitor
1716 Number of the monitor on which conky is running or the message
1717 "Not running in X" if this is the case.
1718 monitor_number
1721 Number of monitors or the message "Not running in X" if this is
1722 the case.
1723 mpd_album
1726 Album in current MPD song
1727 mpd_artist
1730 Artist in current MPD song must be enabled at compile
1731 mpd_bar (height),(width)
1734 Bar of mpd's progress
1735 mpd_bitrate
1738 Bitrate of current song
1739 mpd_elapsed
1742 Song's elapsed time
1743 mpd_file
1746 Prints the file name of the current MPD song
1747 mpd_length
1750 Song's length
1751 mpd_name
1754 Prints the MPD name field
1755 mpd_percent
1758 Percent of song's progress
1759 mpd_random
1762 Random status (On/Off)
1763 mpd_repeat
1766 Repeat status (On/Off)
1767 mpd_smart (max length)
1770 Prints the song name in either the form "artist - title" or file
1771 name, depending on whats available
1772 mpd_status
1775 Playing, stopped, et cetera.
1776 mpd_title (max length)
1779 Title of current MPD song
1780 mpd_track
1783 Prints the MPD track field
1784 mpd_vol
1787 MPD's volume
1788 nameserver (index)
1791 Print a nameserver from /etc/resolv.conf. Index starts at and
1792 defaults to 0.
1793 new_mails (mailbox) (interval)
1796 Unread mail count in the specified mailbox or mail spool if not.
1797 Both mbox and maildir type mailboxes are supported.
1798 nodename
1801 Hostname
1802 nodename_short
1805 Short hostname (same as 'hostname -s' shell command).
1806 nvidia threshold temp ambient gpufreq memfreq imagequality
1809 Nvidia graficcard support for the XNVCtrl library. Each option
1810 can be shortened to the least significant part. Temperatures are
1811 printed as float, all other values as integer.
1812 threshold The thresholdtemperature at which the gpu slows down
1814 temp Gives the gpu current temperature
1815 ambient Gives current air temperature near GPU case
1816 gpufreq Gives the current gpu frequency
1817 memfreq Gives the current mem frequency
1818 imagequality Which imagequality should be chosen by OpenGL ap‐
1819 plications
1820 offset (pixels)
1823 Move text over by N pixels. See also $voffset.
1824 outlinecolor (color)
1827 Change outline color
1828 pb_battery item
1831 If running on Apple powerbook/ibook, display information on bat‐
1832 tery status. The item parameter specifies, what information to
1833 display. Exactly one item must be specified. Valid items are:
1834 status Display if battery is fully charged, charging, discharg‐
1836 ing or absent (running on AC)
1837 percent Display charge of battery in percent, if charging or
1838 discharging. Nothing will be displayed, if battery is fully
1839 charged or absent.
1840 time Display the time remaining until the battery will be fully
1841 charged or discharged at current rate. Nothing is displayed, if
1842 battery is absent or if it's present but fully charged and not
1843 discharging.
1844 pid_chroot pid
1847 Directory used as rootdirectory by the process (this will be "/"
1848 unless the process did a chroot syscall)
1849 pid_cmdline pid
1852 Command line this process was invoked with
1853 pid_cwd pid
1856 Current working directory of the process
1857 pid_environ pid varname
1860 Contents of a environment-var of the process
1861 pid_environ_list pid
1864 List of environment-vars that the process can see
1865 pid_exe pid
1868 Path to executed command that started the process
1869 pid_nice pid
1872 The nice value of the process
1873 pid_openfiles pid
1876 List of files that the process has open
1877 pid_parent pid
1880 The pid of the parent of the process
1881 pid_priority pid
1884 The priority of the process (see 'priority' in "man 5 proc")
1885 pid_read pid
1888 Total number of bytes read by the process
1889 pid_state pid
1892 State of the process
1893 pid_state_short pid
1896 One of the chars in "RSDZTW" representing the state of the
1897 process where R is running, S is sleeping in an interruptible
1898 wait, D is waiting in uninterruptible disk sleep, Z is zombie, T
1899 is traced or stopped (on a signal), and W is paging
1900 pid_stderr pid
1903 Filedescriptor binded to the STDERR of the process
1904 pid_stdin pid
1907 Filedescriptor binded to the STDIN of the process
1908 pid_stdout pid
1911 Filedescriptor binded to the STDOUT of the process
1912 pid_threads pid
1915 Number of threads in process containing this thread
1916 pid_thread_list pid
1919 List with pid's from threads from this process
1920 pid_time_kernelmode pid
1923 Amount of time that the process has been scheduled in kernel
1924 mode in seconds
1925 pid_time_usermode pid
1928 Amount of time that the process has been scheduled in user mode
1929 in seconds
1930 pid_time pid
1933 Sum of $pid_time_kernelmode and $pid_time_usermode
1934 pid_uid pid
1937 The real uid of the process
1938 pid_euid pid
1941 The effective uid of the process
1942 pid_suid pid
1945 The saved set uid of the process
1946 pid_fsuid pid
1949 The file system uid of the process
1950 pid_gid pid
1953 The real gid of the process
1954 pid_egid pid
1957 The effective gid of the process
1958 pid_sgid pid
1961 The saved set gid of the process
1962 pid_fsgid pid
1965 The file system gid of the process
1966 pid_vmpeak pid
1969 Peak virtual memory size of the process
1970 pid_vmsize pid
1973 Virtual memory size of the process
1974 pid_vmlck pid
1977 Locked memory size of the process
1978 pid_vmhwm pid
1981 Peak resident set size ("high water mark") of the process
1982 pid_vmrss pid
1985 Resident set size of the process
1986 pid_vmdata pid
1989 Data segment size of the process
1990 pid_vmstk pid
1993 Stack segment size of the process
1994 pid_vmexe pid
1997 Text segment size of the process
1998 pid_vmlib pid
2001 Shared library code size of the process
2002 pid_vmpte pid
2005 Page table entries size of the process
2006 pid_write pid
2009 Total number of bytes written by the process
2010 platform (dev) type n (factor offset)
2013 Platform sensor from sysfs (Linux 2.6). Parameter dev may be
2014 omitted if you have only one platform device. Platform type is
2015 either 'in' or 'vol' meaning voltage; 'fan' meaning fan; 'temp'
2016 meaning temperature. Parameter n is number of the sensor. See
2017 /sys/bus/platform/devices/ on your local computer. The optional
2018 arguments 'factor' and 'offset' allow precalculation of the raw
2019 input, which is being modified as follows: 'input = input * fac‐
2020 tor + offset'. Note that they have to be given as decimal values
2021 (i.e. contain at least one decimal place).
2022 pop3_unseen (args)
2025 Displays the number of unseen messages in your global POP3 inbox
2026 by default. You can define individual POP3 inboxes separately by
2027 passing arguments to this object. Arguments are: "host user pass
2028 [-i interval (in seconds)] [-p port] [-e 'command'] [-r re‐
2029 tries]". Default port is 110, default interval is 5 minutes, and
2030 default number of retries before giving up is 5. If the password
2031 is supplied as '*', you will be prompted to enter the password
2032 when Conky starts.
2033 pop3_used (args)
2036 Displays the amount of space (in MiB, 2^20) used in your global
2037 POP3 inbox by default. You can define individual POP3 inboxes
2038 separately by passing arguments to this object. Arguments are:
2039 "host user pass [-i interval (in seconds)] [-p port] [-e 'com‐
2040 mand'] [-r retries]". Default port is 110, default interval is 5
2041 minutes, and default number of retries before giving up is 5. If
2042 the password is supplied as '*', you will be prompted to enter
2043 the password when Conky starts.
2044 pre_exec shell command
2047 Executes a shell command one time before conky displays anything
2048 and puts output as text.
2049 processes
2052 Total processes (sleeping and running)
2053 read_tcp (host) port
2056 Connects to a tcp port on a host (default is localhost), reads
2057 every char available at the moment and shows them.
2058 replied_mails (maildir) (interval)
2061 Number of mails marked as replied in the specified mailbox or
2062 mail spool if not. Only maildir type mailboxes are supported,
2063 mbox type will return -1.
2064 rss uri interval_in_minutes action (num_par (spaces_in_front))
2067 Download and parse RSS feeds. The interval may be a floating
2068 point value greater than 0, otherwise defaults to 15 minutes.
2069 Action may be one of the following: feed_title, item_title (with
2070 num par), item_desc (with num par) and item_titles (when using
2071 this action and spaces_in_front is given conky places that many
2072 spaces in front of each item). This object is threaded, and once
2073 a thread is created it can't be explicitly destroyed. One thread
2074 will run for each URI specified. You can use any protocol that
2075 Curl supports.
2076 running_processes
2078 Running processes (not sleeping), requires Linux 2.6
2079 running_threads
2082 Number of running (runnable) threads. Linux only.
2083 scroll length (step) text
2086 Scroll 'text' by 'step' characters showing 'length' number of
2087 characters at the same time. The text may also contain vari‐
2088 ables. 'step' is optional and defaults to 1 if not set. If a var
2089 creates output on multiple lines then the lines are placed be‐
2090 hind each other separated with a '|'-sign. If you change the
2091 textcolor inside $scroll it will automatically have it's old
2092 value back at the end of $scroll. The end and the start of text
2093 will be separated by 'length' number of spaces.
2094 seen_mails (maildir) (interval)
2097 Number of mails marked as seen in the specified mailbox or mail
2098 spool if not. Only maildir type mailboxes are supported, mbox
2099 type will return -1.
2100 shadecolor (color)
2103 Change shading color
2104 smapi (ARGS)
2107 when using smapi, display contents of the /sys/devices/plat‐
2108 form/smapi directory. ARGS are either '(FILENAME)' or 'bat (IN‐
2109 DEX) (FILENAME)' to display the corresponding files' content.
2110 This is a very raw method of accessing the smapi values. When
2111 available, better use one of the smapi_* variables instead.
2112 smapi_bat_bar (INDEX),(height),(width)
2115 when using smapi, display the remaining capacity of the battery
2116 with index INDEX as a bar.
2117 smapi_bat_perc (INDEX)
2120 when using smapi, display the remaining capacity in percent of
2121 the battery with index INDEX. This is a separate variable be‐
2122 cause it supports the 'use_spacer' configuration option.
2123 smapi_bat_power INDEX
2126 when using smapi, display the current power of the battery with
2127 index INDEX in watt. This is a separate variable because the
2128 original read out value is being converted from mW. The sign of
2129 the output reflects charging (positive) or discharging (nega‐
2130 tive) state.
2131 smapi_bat_temp INDEX
2134 when using smapi, display the current temperature of the battery
2135 with index INDEX in degree Celsius. This is a separate variable
2136 because the original read out value is being converted from mil‐
2137 li degree Celsius.
2138 sony_fanspeed
2141 Displays the Sony VAIO fanspeed information if sony-laptop ker‐
2142 nel support is enabled. Linux only.
2143 stippled_hr (space)
2146 Stippled (dashed) horizontal line
2147 swap Amount of swap in use
2150 swapbar (height),(width)
2153 Bar that shows amount of swap in use
2154 swapfree
2157 Amount of free swap
2158 swapmax
2161 Total amount of swap
2162 swapperc
2165 Percentage of swap in use
2166 sysname
2169 System name, Linux for example
2170 tab (width, (start))
2173 Puts a tab of the specified width, starting from column 'start'.
2174 The unit is pixels for both arguments.
2175 tail logfile lines (next_check)
2178 Displays last N lines of supplied text file. The file is checked
2179 every 'next_check' update. If next_check is not supplied, Conky
2180 defaults to 2. Max of 30 lines can be displayed, or until the
2181 text buffer is filled.
2182 tcp_portmon port_begin port_end item (index)
2185 TCP port (both IPv6 and IPv4) monitor for specified local ports.
2186 Port numbers must be in the range 1 to 65535. Valid items are:
2187 count Total number of connections in the range
2189 rip Remote ip address
2190 rhost Remote host name
2191 rport Remote port number
2192 rservice Remote service name from /etc/services
2193 lip Local ip address
2194 lhost Local host name
2195 lport Local port number
2196 lservice Local service name from /etc/services
2197 The connection index provides you with access to each connection
2199 in the port monitor. The monitor will return information for in‐
2200 dex values from 0 to n-1 connections. Values higher than n-1 are
2201 simply ignored. For the "count" item, the connection index must
2202 be omitted. It is required for all other items.
2203 Examples:
2205 ${tcp_portmon 6881 6999 count} Displays the number of connec‐
2207 tions in the bittorrent port range
2208 ${tcp_portmon 22 22 rip 0} Displays the remote host ip of the
2209 first sshd connection
2210 ${tcp_portmon 22 22 rip 9} Displays the remote host ip of the
2211 tenth sshd connection
2212 ${tcp_portmon 1 1024 rhost 0} Displays the remote host name of
2213 the first connection on a privileged port
2214 ${tcp_portmon 1 1024 rport 4} Displays the remote host port of
2215 the fifth connection on a privileged port
2216 ${tcp_portmon 1 65535 lservice 14} Displays the local service
2217 name of the fifteenth connection in the range of all ports
2218 Note that port monitor variables which share the same port range
2220 actually refer to the same monitor, so many references to a sin‐
2221 gle port range for different items and different indexes all use
2222 the same monitor internally. In other words, the program avoids
2223 creating redundant monitors.
2224 templateN (arg1) (arg2) (arg3 ...)
2226 Evaluate the content of the templateN configuration variable
2227 (where N is a value between 0 and 9, inclusively), applying sub‐
2228 stitutions as described in the documentation of the correspond‐
2229 ing configuration variable. The number of arguments is optional,
2230 but must match the highest referred index in the template. You
2231 can use the same special sequences in each argument as the ones
2232 valid for a template definition, e.g. to allow an argument to
2233 contain a whitespace. Also simple nesting of templates is possi‐
2234 ble this way.
2235 Here are some examples of template definitions:
2237 template0 $\1\2
2239 template1 \1: ${fs_used \2} / ${fs_size \2}
2240 template2 \1 \2
2241 The following list shows sample usage of the templates defined
2243 above, with the equivalent syntax when not using any template at
2244 all:
2245 using template same without template
2247 ────────────────────────────────────────────────────────
2248 ${template0 node name} $nodename
2249 ${template1 root /} root: ${fs_free /} /
2250 ${fs_size /}
2251 ${template1 ${template2\ disk root: ${fs_free /} /
2252 disk\ root} /} ${fs_size /}
2253 texeci interval command
2255 Runs a command at an interval inside a thread and displays the
2256 output. Same as $execi, except the command is run inside a
2257 thread. Use this if you have a slow script to keep Conky updat‐
2258 ing. You should make the interval slightly longer then the time
2259 it takes your script to execute. For example, if you have a
2260 script that take 5 seconds to execute, you should make the in‐
2261 terval at least 6 seconds. See also $execi. This object will
2262 clean up the thread when it is destroyed, so it can safely be
2263 used in a nested fashion, though it may not produce the desired
2264 behaviour if used this way.
2265 threads
2268 Total threads
2269 time (format)
2272 Local time, see man strftime to get more information about for‐
2273 mat
2274 to_bytes size
2277 If 'size' is a number followed by a size-unit (kilo‐
2278 byte,mb,GiB,...) then it converts the size to bytes and shows it
2279 without unit, otherwise it just shows 'size'.
2280 top type num
2283 This takes arguments in the form:top (name) (number) Basically,
2284 processes are ranked from highest to lowest in terms of cpu us‐
2285 age, which is what (num) represents. The types are: "name",
2286 "pid", "cpu", "mem", "mem_res", "mem_vsize", "time", "io_perc",
2287 "io_read" and "io_write". There can be a max of 10 processes
2288 listed.
2289 top_io type num
2292 Same as top, except sorted by the amount of I/O the process has
2293 done during the update interval
2294 top_mem type num
2297 Same as top, except sorted by mem usage instead of cpu
2298 top_time type num
2301 Same as top, except sorted by total CPU time instead of current
2302 CPU usage
2303 totaldown (net)
2306 Total download, overflows at 4 GB on Linux with 32-bit arch and
2307 there doesn't seem to be a way to know how many times it has al‐
2308 ready done that before conky has started.
2309 totalup (net)
2312 Total upload, this one too, may overflow
2313 trashed_mails (maildir) (interval)
2316 Number of mails marked as trashed in the specified mailbox or
2317 mail spool if not. Only maildir type mailboxes are supported,
2318 mbox type will return -1.
2319 tztime (timezone (format))
2322 Local time for specified timezone, see man strftime to get more
2323 information about format. The timezone argument is specified in
2324 similar fashion as TZ environment variable. For hints, look in
2325 /usr/share/zoneinfo. e.g. US/Pacific, Europe/Zurich, etc.
2326 gid_name gid
2329 Name of group with this gid
2330 uid_name uid
2333 Username of user with this uid
2334 unflagged_mails (maildir) (interval)
2337 Number of mails not marked as flagged in the specified mailbox
2338 or mail spool if not. Only maildir type mailboxes are supported,
2339 mbox type will return -1.
2340 unforwarded_mails (maildir) (interval)
2343 Number of mails not marked as forwarded in the specified mailbox
2344 or mail spool if not. Only maildir type mailboxes are supported,
2345 mbox type will return -1.
2346 unreplied_mails (maildir) (interval)
2349 Number of mails not marked as replied in the specified mailbox
2350 or mail spool if not. Only maildir type mailboxes are supported,
2351 mbox type will return -1.
2352 unseen_mails (maildir) (interval)
2355 Number of new or unseen mails in the specified mailbox or mail
2356 spool if not. Only maildir type mailboxes are supported, mbox
2357 type will return -1.
2358 updates Number of updates
2361 for debugging
2362 upspeed (net)
2365 Upload speed in suitable IEC units
2366 upspeedf (net)
2369 Upload speed in KiB with one decimal
2370 upspeedgraph (netdev) (height),(width) (gradient colour 1) (gradient
2373 colour 2) (scale) (-t) (-l)
2374 Upload speed graph, colours defined in hex, minus the #. If
2375 scale is non-zero, it becomes the scale for the graph. Uses a
2376 logarithmic scale (to see small numbers) when you use the -l
2377 switch. Takes the switch '-t' to use a temperature gradient,
2378 which makes the gradient values change depending on the ampli‐
2379 tude of a particular graph value (try it and see).
2380 uptime Uptime
2383 uptime_short
2386 Uptime in a shorter format
2387 user_names
2390 Lists the names of the users logged in
2391 user_number
2394 Number of users logged in
2395 user_terms
2398 Lists the consoles in use
2399 user_times
2402 Lists how long users have been logged in for
2403 user_time console
2406 Lists how long the user for the given console has been logged in
2407 for
2408 utime (format)
2411 Display time in UTC (universal coordinate time).
2412 voffset (pixels)
2415 Change vertical offset by N pixels. Negative values will cause
2416 text to overlap. See also $offset.
2417 voltage_mv (n)
2420 Returns CPU #n's voltage in mV. CPUs are counted from 1. If
2421 omitted, the parameter defaults to 1.
2422 voltage_v (n)
2425 Returns CPU #n's voltage in V. CPUs are counted from 1. If omit‐
2426 ted, the parameter defaults to 1.
2427 weather URI locID data_type (interval_in_minutes)
2430 Download, parse and display METAR data.
2431 For the 'URI', there are two possibilities:
2433 http://weather.noaa.gov/pub/data/observations/metar/stations/
2435 http://xoap.weather.com/weather/local/
2436 The first one is free to use but the second requires you to reg‐
2438 ister and obtain your partner ID and license key. These two must
2439 be written, separated by a space, into a file called .xoaprc
2440 which needs to be placed into your home directory.
2441 'locID' must be a valid location identifier for the required
2443 uri. For the NOAA site this must be a valid ICAO (see for in‐
2444 stance https://pilotweb.nas.faa.gov/qryhtml/icao/). For the
2445 weather.com site this must be a valid location ID (see for in‐
2446 stance http://aspnetresources.com/tools/locid.aspx).
2447 'data_type' must be one of the following:
2449 last_update The date and time stamp of the data. The result de‐
2451 pends on the URI used. For the NOAA site it is date (yyyy/mm/dd)
2452 and UTC time. For the weather.com one it is date ([m]m/[d]d/yy)
2453 and Local Time of the station.
2454 temperature
2455 Air temperature (you can use the 'temperature_unit' config set‐
2457 ting to change units)
2458 cloud_cover
2459 The highest cloud cover status
2461 pressure
2462 Air pressure in millibar
2464 wind_speed
2465 Wind speed in km/h
2467 wind_dir
2468 Wind direction
2470 wind_dir_DEG
2471 Compass wind direction
2473 humidity
2474 Relative humidity in %
2476 weather
2477 Any relevant weather event (rain, snow, etc.). This is not used
2479 if you are querying the weather.com site since this data is ag‐
2480 gregated into the cloud_cover one
2481 icon
2482 Weather icon (only for www.weather.com). Can be used together
2484 with the icon kit provided upon registering to their service.
2485 'delay_in_minutes' (optional, default 30) cannot be less than 30
2487 minutes.
2488 This object is threaded, and once a thread is created it can't
2490 be explicitly destroyed. One thread will run for each URI speci‐
2491 fied.
2492 Note that these variables are still EXPERIMENTAL and can be sub‐
2494 ject to many future changes.
2495 weather_forecast URI locID day data_type (interval_in_minutes)
2497 Download, parse and display weather forecast data for a given
2498 day (daytime only).
2499 For the 'URI', for the time being only http://xoap.weath‐
2501 er.com/weather/local/ is supported. See 'weather' above for de‐
2502 tails of usage
2503 'locID', see 'weather' above.
2505 'day' is a number from 0 (today) to 4 (3 days after tomorrow).
2507 'data_type' must be one of the following:
2509 day Day of the week
2511 date Date, in the form MMM DD (ie. Jul 14)
2512 low Minimun temperature (you can use the 'temperature_unit' con‐
2513 fig setting to change units)
2514 hi Maximum temperature (you can use the 'temperature_unit' con‐
2515 fig setting to change units)
2516 icon Weather icon. Can be used together with the icon kit pro‐
2517 vided upon registering to the weather.com service
2518 forecast Weather forecast (sunny, rainy, etc.)
2519 wind_speed Wind speed in km/h
2520 wind_dir Wind direction
2521 wind_dir_DEG Compass wind direction
2522 humidity Relative humidity in %
2523 precipitation Probability of having a precipitation (in %)
2524 'delay_in_minutes' (optional, default 210) cannot be lower than
2526 210 min.
2527 This object is threaded, and once a thread is created it can't
2529 be explicitly destroyed. One thread will run for each URI speci‐
2530 fied. You can use any protocol that Curl supports.
2531 Note that these variables are still EXPERIMENTAL and can be sub‐
2533 ject to many future changes.
2534 wireless_ap (net)
2536 Wireless access point MAC address (Linux only)
2537 wireless_bitrate (net)
2540 Wireless bitrate (ie 11 Mb/s) (Linux only)
2541 wireless_essid (net)
2544 Wireless access point ESSID (Linux only)
2545 wireless_link_bar (height),(width) (net)
2548 Wireless link quality bar (Linux only)
2549 wireless_link_qual (net)
2552 Wireless link quality (Linux only)
2553 wireless_link_qual_max (net)
2556 Wireless link quality maximum value (Linux only)
2557 wireless_link_qual_perc (net)
2560 Wireless link quality in percents (Linux only)
2561 wireless_mode (net)
2564 Wireless mode (Managed/Ad-Hoc/Master) (Linux only)
2565 words textfile
2568 Displays the number of words in the given file
2569 xmms2_album
2572 Album in current XMMS2 song
2573 xmms2_artist
2576 Artist in current XMMS2 song
2577 xmms2_bar (height),(width)
2580 Bar of XMMS2's progress
2581 xmms2_bitrate
2584 Bitrate of current song
2585 xmms2_comment
2588 Comment in current XMMS2 song
2589 xmms2_date
2592 Returns song's date.
2593 xmms2_duration
2596 Duration of current song
2597 xmms2_elapsed
2600 Song's elapsed time
2601 xmms2_genre
2604 Genre in current XMMS2 song
2605 xmms2_id
2608 XMMS2 id of current song
2609 xmms2_percent
2612 Percent of song's progress
2613 xmms2_playlist
2616 Returns the XMMS2 playlist.
2617 xmms2_size
2620 Size of current song
2621 xmms2_smart
2624 Prints the song name in either the form "artist - title" or file
2625 name, depending on whats available
2626 xmms2_status
2629 XMMS2 status (Playing, Paused, Stopped, or Disconnected)
2630 xmms2_timesplayed
2633 Number of times a song was played (presumably).
2634 xmms2_title
2637 Title in current XMMS2 song
2638 xmms2_tracknr
2641 Track number in current XMMS2 song
2642 xmms2_url
2645 Full path to current song
2646
2649 Conky features a Lua Programming API, and also ships with Lua bindings
2650 for some useful libraries. Conky defines certain global functions and
2651 variables which can be accessed from Lua code running in Conky.
2652 To use Lua Conky, you first need to make sure you have a version of
2654 Conky with Lua support enabled (``conky -v'' will report this). Scripts
2655 must first be loaded using the lua_load configuration option. You then
2656 call functions in Lua via Conky's $lua, $lua_read, and Lua hooks.
2657 Be careful when creating threaded objects through the Lua API. You
2659 could wind up with a whole bunch of threads running if a thread is cre‐
2660 ated with each iteration.
2661 At this time, the Lua API should not be considered stable and may
2663 change drastically from one release to another as it matures.
2664 NOTE: In order to accommodate certain features in the cairo library's
2666 API, Conky will export a few additional functions for the creation of
2667 certain structures. These are documented below.
2668 conky_parse(string) function
2670 This function takes a string that is evaluated as per Conky's
2671 TEXT section, and then returns a string with the result.
2672 conky_set_update_interval(number) function
2674 Sets Conky's update interval (in seconds) to 'number'.
2675 conky_window table
2677 This table contains some information about Conky's window. The
2678 following table describes the values contained:
2679 drawable Window's drawable (Xlib Drawable), requires Lua extras
2681 enabled at compile time.
2682 visual Window's visual (Xlib Visual), requires Lua extras en‐
2683 abled at compile time.
2684 display Window's display (Xlib Display), requires Lua extras en‐
2685 abled at compile time.
2686 width Window width (in pixels).
2687 height Window height (in pixels).
2688 border_inner_margin Window's inner border margin (in pixels).
2689 border_outer_margin Window's outer border margin (in pixels).
2690 border_width Window's border width (in pixels).
2691 text_start_x The x component of the starting coordinate of text
2692 drawing.
2693 text_start_y The y component of the starting coordinate of text
2694 drawing.
2695 text_width The width of the text drawing region.
2696 text_height The height of the text drawing region.
2697 NOTE: This table is only defined when X support is enabled.
2699 conky_info table
2701 This table contains some information about Conky's internal da‐
2702 ta. The following table describes the values contained:
2703 update_interval Conky's update interval (in seconds).
2705 uptime System uptime, in seconds.
2706 conky_build_info string
2708 A string containing the build info for this particular instance
2709 of Conky, including the version, build date, and architecture.
2710 conky_build_date string
2712 A string containing the build date for this particular instance
2713 of Conky.
2714 conky_build_arch string
2716 A string containing the build architecture for this particular
2717 instance of Conky.
2718 conky_version string
2720 A string containing the version of the current instance of
2721 Conky.
2722 conky_config string
2724 A string containing the path of the current Conky configuration
2725 file.
2726 cairo_text_extents_t:create() function
2728 Call this function to return a new cairo_text_extents_t struc‐
2729 ture. A creation function for this structure is not provided by
2730 the cairo API. After calling this, you should use tolua.takeown‐
2731 ership() on the return value to ensure ownership is passed prop‐
2732 erly.
2733 cairo_font_extents_t:create() function
2735 Call this function to return a new cairo_font_extents_t struc‐
2736 ture. A creation function for this structure is not provided by
2737 the cairo API. After calling this, you should use tolua.takeown‐
2738 ership() on the return value to ensure ownership is passed prop‐
2739 erly.
2740 cairo_matrix_t:create() function
2742 Call this function to return a new cairo_matrix_t structure. A
2743 creation function for this structure is not provided by the
2744 cairo API. After calling this, you should use tolua.takeowner‐
2745 ship() on the return value to ensure ownership is passed proper‐
2746 ly.
2747
2749 conky -t '${time %D %H:%M}' -o -u 30
2750 Start Conky in its own window with date and clock as text and 30
2751 sec update interval.
2752 conky -a top_left -x 5 -y 500 -d
2754 Start Conky to background at coordinates (5, 500).
2755 conky -C > ~/.conkyrc
2757 Do not start Conky, but have it output the builtin default con‐
2758 fig file to ~/.conkyrc for later customising.
2759
2761 ${sysconfdir}/conky/conky.conf
2762 Default system-wide configuration file. The value of
2763 ${sysconfdir} depends on the compile-time options (most likely
2764 /etc).
2765 ~/.conkyrc
2767 Default personal configuration file.
2768
2770 Drawing to root or some other desktop window directly doesn't work with
2771 all window managers. Especially doesn't work well with Gnome and it has
2772 been reported that it doesn't work with KDE either. Nautilus can be
2773 disabled from drawing to desktop with program gconf-editor. Uncheck
2774 show_desktop in /apps/nautilus/preferences/. There is -w switch in
2775 Conky to set some specific window id. You might find xwininfo -tree
2776 useful to find the window to draw to. You can also use -o argument
2777 which makes Conky to create its own window. If you do try running Conky
2778 in its own window, be sure to read up on the own_window_type settings
2779 and experiment.
2780
2782 ⟨http://conky.sourceforge.net/⟩
2783 ⟨http://www.sourceforge.net/projects/conky⟩
2785 ⟨http://wiki.conky.be⟩
2787 #conky on irc.freenode.net
2789
2791 Copyright (c) 2005-2010 Brenden Matthews, Philip Kovacs, et. al. Any
2792 original torsmo code is licensed under the BSD license (see LICENSE.BSD
2793 for a copy). All code written since the fork of torsmo is licensed un‐
2794 der the GPL (see LICENSE.GPL for a copy), except where noted different‐
2795 ly (such as in portmon code, timed thread code, and audacious code
2796 which are LGPL, and prss which is an MIT-style license).
2797
2799 The Conky dev team (see AUTHORS for a full list of contributors).
2800 2010-10-05 conky(1)