X-Git-Url: http://vcs.maemo.org/git/?a=blobdiff_plain;f=README;h=06cc1ac456b481ff01cc511fb520c06ea2a95e3f;hb=HEAD;hp=0bd563c9f17304062180bc74bdef447ba6a3d524;hpb=eccc149697c888e8fc841c863994fc6fd8bda4f9;p=monky diff --git a/README b/README index 0bd563c..06cc1ac 100644 --- a/README +++ b/README @@ -1,4 +1,4 @@ -conky(1) conky(1) +conky(1) conky(1) @@ -7,46 +7,65 @@ NAME more kickass. It just keeps on given'er. Yeah. SYNOPSIS - conky [options] + conky [ options ] DESCRIPTION - Conky is a system monitor for X originally based on the torsmo code. - Since it's original conception, Conky has changed a fair bit from it's - predecessor. Conky can display just about anything, either on your - root desktop or in it's own window. Conky has many built-in objects, - as well as the ability to execute programs and scripts, then display - the output from stdout. - - We are always looking for help, and anyone interested in becoming a de- - veloper is welcome. Please use the facilities at SourceForge to make - bug reports, feature requests, and submit patches. + Conky is a system monitor for X originally based on torsmo. Since its + inception, Conky has changed significantly from its predecessor, while + maintaining simplicity and configurability. Conky can display just + about anything, either on your root desktop or in its own window. Not + only does Conky have many built-in objects, it can also display just + about any piece of information by using scripts and other external pro- + grams. + + Conky has more than 250 built in objects, including support for a + plethora of OS stats (uname, uptime, CPU usage, mem usage, disk usage, + "top" like process stats, and network monitoring, just to name a few), + built in IMAP and POP3 support, built in support for many popular music + players (MPD, XMMS2, BMPx, Audacious), and much much more. Conky can + display this info either as text, or using simple progress bars and + graph widgets, with different fonts and colours. + + We are always looking for help, whether its reporting bugs, writing + patches, or writing docs. Please use the facilities at SourceForge to + make bug reports, feature requests, and submit patches, or stop by + #conky on irc.freenode.net if you have questions or want to contribute. Thanks for your interest in Conky. COMPILING - For users compiling from source, make sure you have the X development - libraries installed. This should be a package along the lines of - "libx11-dev or xorg-x11-dev". - - Gentoo users -- Conky is in Gentoo's Portage... simply use "emerge app- - admin/conky" for installation. There is also usually an up-to-date - ebuild within Conky's package or in Svn. - - Debian,etc. users -- Conky will be in Debian's repositories soon (by - mid-September, hopefully), and then Ubuntu shortly thereafter. Until - then, "dpkg -i" the .deb package to install. - - Example to compile and run Conky with all optional components (note + For users compiling from source on a binary distro, make sure you have + the X development libraries installed (Unless you provide configure + with "--disable-x11"). This should be a package along the lines of + "libx11-dev" or "xorg-x11-dev" for X11 libs, and similar "-dev" format + for the other libs required (depending on your configure options). You + should be able to see which extra packages you need to install by read- + ing errors that you get from './configure'. You can enable/disable + stuff by giving options to configure, but be careful with disabling. + For example: with --disable-math you won't get errors but logarithmic + graphs will be normal graphs and gauges will miss their line. + + Conky has (for some time) been available in the repositories of most + popular distributions. Here are some installation instructions for a + few: + + Gentoo users -- Conky is in Gentoo's Portage... simply use "emerge + app-admin/conky" for installation. + + Debian, etc. users -- Conky should be in your repositories, and can be + installed by doing "aptitude install conky". + + Example to compile and run Conky with all optional components (note that some configure options may differ for your system): - sh autogen.sh # Only required if building from Svn + sh autogen.sh # Only required if building from the git repo - ./configure --prefix=/usr --mandir=/usr/share/man --in- - fodir=/usr/share/info --datadir=/usr/share --sysconfdir=/etc --local- - statedir=/var/lib --disable-own-window --enable-audacious --enable-bmpx - --disable-hddtemp --disable-mpd --enable-xmms2 --disable-portmon --dis- - able-network --enable-debug --disable-x11 --disable-double-buffer - --disable-xdamage --disable-xft + ./configure --prefix=/usr --mandir=/usr/share/man --in- + fodir=/usr/share/info --datadir=/usr/share --sysconfdir=/etc --local- + statedir=/var/lib --disable-own-window --enable-audacious[=yes|no|lega- + cy] --enable-bmpx --disable-hddtemp --disable-mpd --enable-xmms2 --dis- + able-portmon --disable-network --enable-debug --disable-x11 --dis- + able-double-buffer --disable-xdamage --disable-xft make @@ -54,1351 +73,2718 @@ COMPILING src/conky - Conky probably doesn't compile with compilers other than gcc and icc. - It doesn't compile with C89 compiler and not even with pure C99. It - uses a few things that might not exist: strdup(), strcasecmp(), strn- - casecmp(), optarg variable with getopt() and long long (not in C89). - Crashes in file system statistics stuff when compiled with icc, I don't - know exactly why. - - You can disable 'drawing to own window' feature in case you don't need - it by passing --disable-own-window to configure -script. - + Conky has been tested to be compatible with C99 C, however it has not + been tested with anything other than gcc, and is not guaranteed to work + with other compilers. YOU SHOULD KNOW - Conky is generally very good on resources. However, certain objects in - Conky are harder on resources then others. In particular, the $tail, - $top, $font, and $graph objects are quite costly in comparison to the - rest of Conky. - - If you do use them, please do not complain about memory or CPU usage, - unless you think something's seriously wrong (mem leak, etc.). + Conky is generally very good on resources. That said, the more you try + to make Conky do, the more resources it is going to consume. An easy way to force Conky to reload your ~/.conkyrc: "killall -SIGUSR1 - conky". Saves you the trouble of having to kill and then restart. - - IMPORTANT: For previous Conky users, Conky 1.3 no longer supports the - metar stuff. mdsplib was causing way too many problems. Hopefully - there'll be a better solution in Conky 2.x... + conky". Saves you the trouble of having to kill and then restart. You + can now also do the same with SIGHUP. OPTIONS - Command line options override configurations defined in configuration + Command line options override configurations defined in configuration file. - -v | -V - Prints version and exits + -v | -V | --version + Prints version and exits - -a ALIGNMENT - Text alignment on screen, {top,bottom}_{left,right} or none + -q | --quiet + Run Conky in 'quiet mode' (ie. no output) - -b Use double buffering (eliminates "flicker") + -D | --debug + Increase debugging output, ie. -DD for more debugging - -c FILE - Config file to load instead of $HOME/.conkyrc + -a | --alignment= ALIGNMENT + Text alignment on screen, {top,bottom,middle}_{left,right,mid- + dle} or none. Can also be abbreviated with first chars of posi- + tion, ie. tr for top_right. - -d Daemonize Conky, aka fork to background + -b | --double-buffer + Use double buffering (eliminates "flicker") - -f FONT - Font to use + -c | --config= FILE + Config file to load instead of $HOME/.conkyrc - -h Prints command line help and exits + -C | --print-config + Print builtin default config to stdout. See also the section EX- + AMPLES for more information. - -o Create own window to draw + -d | --daemonize + Daemonize Conky, aka fork to background - -t TEXT - Text to render, remember single quotes, like -t ' $uptime ' + -f | --font= FONT + Font to use - -u SECONDS - Update interval + -h | --help + Prints command line help and exits - -w WIN_ID - Window id to draw + -o | --own-window + Create own window to draw - -x X_COORDINATE - X position + -t | --text= TEXT + Text to render, remember single quotes, like -t ' $uptime ' - -y Y_COORDINATE - Y position + -p | --pause= SECONDS + Time to pause before actually starting Conky -CONFIGURATION SETTINGS - Default configuration file is $HOME/.conkyrc (can be changed from - conky.c among other things). See conkyrc.sample. If installing from De- - bian package, this should be in /usr/share/doc/conky/examples ("gunzip - conkyrc.sample.gz" to get conkyrc.sample). + -u | --interval= SECONDS + Update interval - You might want to copy it to $HOME/.conkyrc and then start modifying - it. Other configs can be found at http://conky.sf.net - alignment - Aligned position on screen, may be top_left, top_right, bot- - tom_left, bottom_right, or none + -w | --window-id= WIN_ID + Window id to draw - background - Boolean value, if true, Conky will be forked to background when - started + -X | --display= DISPLAY + X11 display to use - border_margin - Border margin in pixels + -x X_COORDINATE + X position - border_width - Border width in pixels + -y Y_COORDINATE + Y position - color0 A color variable for use inside TEXT segments + -i COUNT + Number of times to update Conky (and quit) - color1 A color variable for use inside TEXT segments +CONFIGURATION SETTINGS + Default configuration file location is $HOME/.conkyrc or + ${sysconfdir}/conky/conky.conf. On most systems, sysconfdir is /etc, + and you can find the sample config file there (/etc/conky/conky.conf). + You might want to copy it to $HOME/.conkyrc and then start modifying + it. Other configs can be found at http://conky.sf.net/ - color2 A color variable for use inside TEXT segments + TEXT After this begins text to be formatted on screen. Backslash (\) + escapes newlines in the text section. This can be useful for + cleaning up config files where conky is used to pipe input to + dzen2. - color3 A color variable for use inside TEXT segments + alignment + Aligned position on screen, may be top_left, top_right, top_mid- + dle, bottom_left, bottom_right, bottom_middle, middle_left, mid- + dle_middle, middle_right, or none (also can be abreviated as tl, + tr, tm, bl, br, bm, ml, mm, mr). See also gap_x and gap_y. - color4 A color variable for use inside TEXT segments + append_file + Append the file given as argument. - color5 A color variable for use inside TEXT segments + background + Boolean value, if true, Conky will be forked to background when + started. - color6 A color variable for use inside TEXT segments + border_inner_margin + Inner border margin in pixels (the margin between the border and + text). - color7 A color variable for use inside TEXT segments + border_outer_margin + Outer border margin in pixels (the margin between the border and + the edge of the window). - color8 A color variable for use inside TEXT segments + border_width + Border width in pixels. - color9 A color variable for use inside TEXT segments + colorN Predefine a color for use inside TEXT segments. Substitute N by + a digit between 0 and 9, inclusively. When specifying the color + value in hex, omit the leading hash (#). cpu_avg_samples - The number of samples to average for CPU monitoring + The number of samples to average for CPU monitoring. + + + default_bar_size + Specify a default width and height for bars. Example: 'de- + fault_bar_size 0 6'. This is particularly useful for execbar and + execibar as they do not take size arguments. default_color - Default color and border color + Default color and border color + + + default_gauge_size + Specify a default width and height for gauges. Example: 'de- + fault_gauge_size 25 25'. This is particularly useful for exec- + gauge and execigauge as they do not take size arguments + + + default_graph_size + Specify a default width and height for graphs. Example: 'de- + fault_graph_size 0 25'. This is particularly useful for exec- + graph and execigraph as they do not take size arguments default_outline_color - Default outline color + Default outline color default_shade_color - Default shading color and border's shading color + Default shading color and border's shading color + + + disable_auto_reload + Enable to disable the inotify-based auto config reload feature. + + + diskio_avg_samples + The number of samples to average for disk I/O monitoring. + + + display + Specify an X display to connect to. double_buffer - Use the Xdbe extension? (eliminates flicker) It is highly recom- - mended to use own window with this one so double buffer won't be - so big. + Use the Xdbe extension? (eliminates flicker) It is highly recom- + mended to use own window with this one so double buffer won't be + so big. draw_borders - Draw borders around text? + Draw borders around text? draw_graph_borders - Draw borders around graphs? + Draw borders around graphs? draw_outline - Draw outlines? + Draw outlines? draw_shades - Draw shades? + Draw shades? + + + extra_newline + Put an extra newline at the end when writing to stdout, useful + for writing to awesome's wiboxes. font Font name in X, xfontsel can be used to get a nice font + format_human_readable + If enabled, values which are in bytes will be printed in human + readable format (i.e., KiB, MiB, etc). If disabled, the number + of bytes is printed instead. + + gap_x Gap, in pixels, between right or left border of screen, same as - passing -x at command line, e.g. gap_x 10 + passing -x at command line, e.g. gap_x 10. For other position + related stuff, see 'alignment'. + + + gap_y Gap, in pixels, between top or bottom border of screen, same as + passing -y at command line, e.g. gap_y 10. For other position + related stuff, see 'alignment'. + + + hddtemp_host + Hostname to connect to for hddtemp objects. Defaults to + "127.0.0.1". - gap_y Gap, in pixels, between top or bottom border of screen, same as - passing -y at command line, e.g. gap_y 10. + hddtemp_port + Port to use for hddtemp connections. Defaults to 7634. + + + if_up_strictness + How strict should if_up be when testing an interface for being + up? The value is one of up, link or address, to check for the + interface being solely up, being up and having link or being up, + having link and an assigned IP address. imap Default global IMAP server. Arguments are: "host user pass [-i - interval] [-f folder] [-p port] [-e command]". Default port is - 143, default folder is 'INBOX', default interval is 5 minutes. - If the password is supplied as '*', you will be prompted to en- - ter the password when Conky starts. + interval (in seconds)] [-f 'folder'] [-p port] [-e 'command'] + [-r retries]". Default port is 143, default folder is 'INBOX', + default interval is 5 minutes, and default number of retries be- + fore giving up is 5. If the password is supplied as '*', you + will be prompted to enter the password when Conky starts. + + + imlib_cache_flush_interval + Interval (in seconds) to flush Imlib2 cache. + + + imlib_cache_size + Imlib2 image cache size, in bytes. Defaults to 4MiB. Increase + this value if you use $image lots. Set to 0 to disable the image + cache. + + + lua_draw_hook_post function_name [function arguments] + This function, if defined, will be called by Conky through each + iteration after drawing to the window. Requires X support. Takes + any number of optional arguments. Use this hook for drawing + things on top of what Conky draws. Conky puts 'conky_' in front + of function_name to prevent accidental calls to the wrong func- + tion unless you place 'conky_' in front of it yourself. + + + lua_draw_hook_pre function_name [function arguments] + This function, if defined, will be called by Conky through each + iteration before drawing to the window. Requires X support. + Takes any number of optional arguments. Use this hook for draw- + ing things on top of what Conky draws. Conky puts 'conky_' in + front of function_name to prevent accidental calls to the wrong + function unless you place 'conky_' in front of it yourself. + + + lua_load + Loads the Lua scripts separated by spaces. + + + lua_shutdown_hook function_name [function arguments] + This function, if defined, will be called by Conky at shutdown + or when the configuration is reloaded. Use this hook to clean up + after yourself, such as freeing memory which has been allocated + by external libraries via Lua. Conky puts 'conky_' in front of + function_name to prevent accidental calls to the wrong function + unless you place 'conky_' in front of it yourself. + + + lua_startup_hook function_name [function arguments] + This function, if defined, will be called by Conky at startup or + when the configuration is reloaded. Use this hook to initialize + values, or for any run-once applications. Conky puts 'conky_' in + front of function_name to prevent accidental calls to the wrong + function unless you place 'conky_' in front of it yourself. mail_spool - Mail spool for mail checking + Mail spool for mail checking max_port_monitor_connections - Allow each port monitor to track at most this many connections - (if 0 or not set, default is 256) + Allow each port monitor to track at most this many connections + (if 0 or not set, default is 256) max_specials - Maximum number of special things, e.g. fonts, offsets, aligns, - etc. (default is 512) + Maximum number of special things, e.g. fonts, offsets, aligns, + etc. (default is 512) - max_user_text bytes - Maximum size of user text buffer, i.e. layout below TEXT line in - config file (default is 16384 bytes) + max_text_width width + When a line in the output contains 'width' chars and the end + isn't reached, the next char will start on a new line. If you + want to make sure that lines don't get broken, set 'width' to 0 - text_buffer_size bytes - Size of the standard text buffer (default is 1280 bytes). + max_user_text bytes + Maximum size of user text buffer, i.e. layout below TEXT line in + config file (default is 16384 bytes) maximum_width pixels - Maximum width of window + Maximum width of window minimum_size width (height) - Minimum size of window + Minimum size of window mpd_host - Host of MPD server + Host of MPD server - mpd_port - Port of MPD server + mpd_password + MPD server password - mpd_password - MPD server password + mpd_port + Port of MPD server music_player_interval - Music player thread update interval (defaults to Conky's update - interval) + Music player thread update interval (defaults to Conky's update + interval) net_avg_samples - The number of samples to average for net data + The number of samples to average for net data no_buffers - Substract (file system) buffers from used memory? + Subtract (file system) buffers from used memory? + + + out_to_console + Print text to stdout. + + + out_to_ncurses + Print text in the console, but use ncurses so that conky can + print the text of a new update over the old text. (In the future + this will provide more useful things) + + + out_to_stderr + Print text to stderr. + + + out_to_x + When set to no, there will be no output in X (useful when you + also use things like out_to_console). If you set it to no, make + sure that it's placed before all other X-related setting (take + the first line of your configfile to be sure). Default value is + yes override_utf8_locale - Force UTF8? requires XFT + Force UTF8? requires XFT + + + overwrite_file + Overwrite the file given as argument. own_window - Boolean, create own window to draw? + Boolean, create own window to draw? own_window_class - Manually set the WM_CLASS name. Defaults to "Conky". + Manually set the WM_CLASS name. Defaults to "Conky". own_window_colour colour - If own_window_transparent no, set a specified background colour - (defaults to black). Takes either a hex value (#ffffff) or a - valid RGB name (see /usr/lib/X11/rgb.txt) + If own_window_transparent no, set a specified background colour + (defaults to black). Takes either a hex value (e.g. ffffff, note + the lack of '#') or a valid RGB name (see /usr/lib/X11/rgb.txt) own_window_hints undecorated,below,above,sticky,skip_taskbar,skip_pager - If own_window is yes, you may use these window manager hints to - affect the way Conky displays. Notes: Use own_window_type desk- - top as another way to implement many of these hints implicitly. - If you use own_window_type override, window manager hints have - no meaning and are ignored. + If own_window is yes, you may use these window manager hints to + affect the way Conky displays. Notes: Use own_window_type desk- + top as another way to implement many of these hints implicitly. + If you use own_window_type override, window manager hints have + no meaning and are ignored. own_window_title - Manually set the window name. Defaults to " - conky". + Manually set the window name. Defaults to " - conky". + + + own_window_argb_visual + Boolean, use ARGB visual? ARGB can be used for real transparen- + cy, note that a composite manager is required for real trans- + parency. This option will not work as desired (in most cases) in + conjunction with 'own_window_type override'. + + + own_window_argb_value + When ARGB visuals are enabled, this use this to modify the alpha + value used. Valid range is 0-255, where 0 is 0% opacity, and 255 + is 100% opacity. Note that if own_window_transparent is enabled, + this value has no effect. own_window_transparent - Boolean, set pseudo-transparency? + Boolean, set transparency? If ARGB visual is enabled, sets back- + ground opacity to 0%. own_window_type - if own_window is yes, you may specify type normal, desktop or - override (default: normal). Desktop windows are special windows - that have no window decorations; are always visible on your - desktop; do not appear in your pager or taskbar; and are sticky - across all workspaces. Override windows are not under the con- - trol of the window manager. Hints are ignored. This type of win- - dow can be useful for certain situations. + if own_window is yes, you may specify type normal, desktop, + dock, panel or override (default: normal). Desktop windows are + special windows that have no window decorations; are always vis- + ible on your desktop; do not appear in your pager or taskbar; + and are sticky across all workspaces. Panel windows reserve + space along a desktop edge, just like panels and taskbars, pre- + venting maximized windows from overlapping them. The edge is + chosen based on the alignment option. Override windows are not + under the control of the window manager. Hints are ignored. This + type of window can be useful for certain situations. - out_to_console - Print text to stdout. + pad_percents + Pad percentages to this many decimals (0 = no padding) - pad_percents - Pad percentages to this many decimals (0 = no padding) + pop3 Default global POP3 server. Arguments are: "host user pass [-i + interval (in seconds)] [-p port] [-e 'command'] [-r retries]". + Default port is 110, default interval is 5 minutes, and default + number of retries before giving up is 5. If the password is sup- + plied as '*', you will be prompted to enter the password when + Conky starts. + + + short_units + Shortens units to a single character (kiB->k, GiB->G, etc.). De- + fault is off. + + show_graph_range + Shows the time range covered by a graph. - pop3 Default global POP3 server. Arguments are: "host user pass [-i - interval] [-p port] [-e command]". Default port is 110, default - interval is 5 minutes. If the password is supplied as '*', you - will be prompted to enter the password when Conky starts. + + show_graph_scale + Shows the maximum value in scaled graphs. stippled_borders - Border stippling (dashing) in pixels + Border stippling (dashing) in pixels + + + temperature_unit + Desired output unit of all objects displaying a temperature. Pa- + rameters are either "fahrenheit" or "celsius". The default unit + is degree Celsius. + + + templateN + Define a template for later use inside TEXT segments. Substitute + N by a digit between 0 and 9, inclusively. The value of the + variable is being inserted into the stuff below TEXT at the cor- + responding position, but before some substitutions are applied: + + '\n' -> newline + '\\' -> backslash + '\ ' -> space + '\N' -> template argument N + + + text_buffer_size bytes + Size of the standard text buffer (default is 256 bytes). This + buffer is used for intermediary text, such as individual lines, + output from $exec vars, and various other variables. Increasing + the size of this buffer can drastically reduce Conky's perfor- + mance, but will allow for more text display per variable. The + size of this buffer cannot be smaller than the default value of + 256 bytes. + + + times_in_seconds + If true, variables that output times output a number that repre- + sents seconds. This doesn't affect $time, $tztime and $utime + + + top_cpu_separate + If true, cpu in top will show usage of one processor's power. If + false, cpu in top will show the usage of all processors' power + combined. + + + top_name_width + Width for $top name value (defaults to 15 characters). total_run_times - Total number of times for Conky to update before quitting. Zero - makes Conky run forever + Total number of times for Conky to update before quitting. Zero + makes Conky run forever + + update_interval seconds + Update interval - update_interval - Update interval in seconds + + update_interval_on_battery seconds + Update interval when running on batterypower uppercase - Boolean value, if true, text is rendered in upper case + Boolean value, if true, text is rendered in upper case use_spacer - Adds spaces after certain objects to stop them from moving other - things around. Note that this only helps if you are using a mono - font, such as Bitstream Vera Sans Mono. + Adds spaces around certain objects to stop them from moving oth- + er things around. Arguments are left, right, and none (default). + The old true/false values are deprecated and default to + right/none respectively. Note that this only helps if you are + using a mono font, such as Bitstream Vera Sans Mono. use_xft - Use Xft (anti-aliased font and stuff) + Use Xft (anti-aliased font and stuff) xftalpha - Alpha of Xft font. Must be a value at or between 1 and 0. + Alpha of Xft font. Must be a value at or between 1 and 0. xftfont - Xft font to use. - - - TEXT After this begins text to be formatted on screen - + Xft font to use. -VARIABLES - Colors are parsed using XParsecolor(), there might be a list of them: - /usr/X11R6/lib/X11/rgb.txt. Also, . - Color can be also in #rrggbb format (hex). Note that when displaying - bytes, power is 1024 and not 1000 so 1M really means 1024*1024 bytes - and not 1000*1000. - addr interface - IP address for an interface +OBJECTS/VARIABLES + Colours are parsed using XParsecolor(), there might be a list of them: + /usr/share/X11/rgb.txt. Colour can be also in #rrggbb format (hex). + Some objects may create threads, and sometimes these threads will not + be destroyed until Conky terminates. There is no way to destroy or + clean up threads while Conky is running. For example, if you use an MPD + variable, the MPD thread will keep running until Conky dies. Some + threaded objects will use one of the parameters as a 'key', so that you + only have 1 relevant thread running (for example, the $curl, $rss and + $weather objects launch one thread per URI). - acpiacadapter - ACPI ac adapter state. + acpiacadapter (adapter) + ACPI ac adapter state. On linux, the adapter option specifies + the subfolder of /sys/class/power_supply containing the state + information (defaults to "AC"). Other systems ignore it. acpifan - ACPI fan state + ACPI fan state acpitemp - ACPI temperature in C. + ACPI temperature in C. - acpitempf - ACPI temperature in F. + addr (interface) + IP address for an interface, or "No Address" if no address is + assigned. + + + addrs (interface) + IP addresses for an interface (if one - works like addr). Linux + only. adt746xcpu - CPU temperature from therm_adt746x + CPU temperature from therm_adt746x adt746xfan - Fan speed from therm_adt746x + Fan speed from therm_adt746x + + + alignc (num) + Align text to centre alignr (num) - Right-justify text, with space of N + Right-justify text, with space of N - alignc (num) - Align text to centre + apcupsd host port + Sets up the connection to apcupsd daemon. Prints nothing, de- + faults to localhost:3551 + + + apcupsd_cable + Prints the UPS connection type. + + + apcupsd_charge + Current battery capacity in percent. + + + apcupsd_lastxfer + Reason for last transfer from line to battery. + + + apcupsd_linev + Nominal input voltage. + + + apcupsd_load + Current load in percent. + + + apcupsd_loadbar + Bar showing current load. + + + apcupsd_loadgauge (height),(width) + Gauge that shows current load. + + + apcupsd_loadgraph (height),(width) (gradient colour 1) (gradient colour + 2) (scale) (-t) (-l) + History graph of current load. + + + apcupsd_model + Prints the model of the UPS. + + + apcupsd_name + Prints the UPS user-defined name. + + + apcupsd_status + Prints current status (on-line, on-battery). + + + apcupsd_temp + Current internal temperature. + + + apcupsd_timeleft + Time left to run on battery. + + + apcupsd_upsmode + Prints the UPS mode (e.g. standalone). apm_adapter - Display APM AC adapter status (FreeBSD only) + Display APM AC adapter status (FreeBSD only) apm_battery_life - Display APM battery life in percent (FreeBSD only) + Display APM battery life in percent (FreeBSD only) apm_battery_time - Display remaining APM battery life in hh:mm:ss or "unknown" if - AC adapterstatus is on-line or charging (FreeBSD only) + Display remaining APM battery life in hh:mm:ss or "unknown" if + AC adapterstatus is on-line or charging (FreeBSD only) audacious_bar (height),(width) - Progress bar + Progress bar audacious_bitrate - Bitrate of current tune + Bitrate of current tune audacious_channels - Number of audio channels of current tune + Number of audio channels of current tune audacious_filename - Full path and filename of current tune + Full path and filename of current tune audacious_frequency - Sampling frequency of current tune + Sampling frequency of current tune audacious_length - Total length of current tune as MM:SS + Total length of current tune as MM:SS audacious_length_seconds - Total length of current tune in seconds + Total length of current tune in seconds - audacious_playlist_position - Playlist position of current tune + audacious_main_volume + The current volume fetched from Audacious audacious_playlist_length - Number of tunes in playlist + Number of tunes in playlist + + + audacious_playlist_position + Playlist position of current tune audacious_position - Position of current tune (MM:SS) + Position of current tune (MM:SS) audacious_position_seconds - Position of current tune in seconds + Position of current tune in seconds audacious_status - Player status (Playing/Paused/Stopped/Not running) + Player status (Playing/Paused/Stopped/Not running) audacious_title (max length) - Title of current tune with optional maximum length specifier + Title of current tune with optional maximum length specifier battery (num) - Battery status and remaining percentage capacity of ACPI or APM - battery. ACPI battery number can be given as argument (default - is BAT0). + Battery status and remaining percentage capacity of ACPI or APM + battery. ACPI battery number can be given as argument (default + is BAT0). battery_bar (height),(width) (num) - Battery percentage remaining of ACPI battery in a bar. ACPI bat- - tery number can be given as argument (default is BAT0). + Battery percentage remaining of ACPI battery in a bar. ACPI bat- + tery number can be given as argument (default is BAT0). battery_percent (num) - Battery percentage remaining for ACPI battery. ACPI battery num- - ber can be given as argument (default is BAT0). + Battery percentage remaining for ACPI battery. ACPI battery + number can be given as argument (default is BAT0). + + + battery_short (num) + Battery status and remaining percentage capacity of ACPI or APM + battery. ACPI battery number can be given as argument (default + is BAT0). This mode display a short status, which means that C + is displayed instead of charging, D for discharging, F for full, + N for not present, E for empty and U for unknown. battery_time (num) - Battery charge/discharge time remaining of ACPI battery. ACPI - battery number can be given as argument (default is BAT0). + Battery charge/discharge time remaining of ACPI battery. ACPI + battery number can be given as argument (default is BAT0). - bmpx_artist - Artist in current BMPx track + blink text_and_other_conky_vars + Let 'text_and_other_conky_vars' blink on and off. bmpx_album - Album in current BMPx track + Album in current BMPx track - bmpx_title - Title of the current BMPx track + bmpx_artist + Artist in current BMPx track - bmpx_track - Track number of the current BMPx track + bmpx_bitrate + Bitrate of the current BMPx track - bmpx_bitrate - Bitrate of the current BMPx track + bmpx_title + Title of the current BMPx track + + + bmpx_track + Track number of the current BMPx track bmpx_uri - URI of the current BMPx track + URI of the current BMPx track buffers - Amount of memory buffered + Amount of memory buffered cached Amount of memory cached + cmdline_to_pid string + PID of the first process that has string in it's commandline + + color (color) - Change drawing color to color + Change drawing color to 'color' which is a name of a color or a + hexcode preceded with # (for example #0A1B2C ). If you use + ncurses only the following colors are supported: red,green,yel- + low,blue,magenta,cyan,black,white. - color0 Change drawing color to color0 configuration option + colorN Change drawing color to colorN configuration option, where N is + a digit between 0 and 9, inclusively. - color1 Change drawing color to color1 configuration option + combine var1 var2 + Places the lines of var2 to the right of the lines of var1 sepa- + rated by the chars that are put between var1 and var2. For exam- + ple: ${combine ${head /proc/cpuinfo 2} - ${head /proc/meminfo + 1}} gives as output "cpuinfo_line1 - meminfo_line1" on line 1 + and "cpuinfo_line2 -" on line 2. $combine vars can also be nest- + ed to place more vars next to each other. - color2 Change drawing color to color2 configuration option + conky_build_arch + CPU architecture Conky was built for - color3 Change drawing color to color3 configuration option + conky_build_date + Date Conky was built - color4 Change drawing color to color4 configuration option + conky_version + Conky version - color5 Change drawing color to color5 configuration option + cpu (cpuN) + CPU usage in percents. For SMP machines, the CPU number can be + provided as an argument. ${cpu cpu0} is the total usage, and + ${cpu cpuX} (X >= 1) are individual CPUs. - color6 Change drawing color to color6 configuration option + cpubar (cpuN) (height),(width) + Bar that shows CPU usage, height is bar's height in pixels. See + $cpu for more info on SMP. - color7 Change drawing color to color7 configuration option + cpugauge (cpuN) (height),(width) + Elliptical gauge that shows CPU usage, height and width are + gauge's vertical and horizontal axis respectively. See $cpu for + more info on SMP. - color8 Change drawing color to color8 configuration option + cpugraph (cpuN) (height),(width) (gradient colour 1) (gradient colour + 2) (scale) (-t) (-l) + CPU usage graph, with optional colours in hex, minus the #. See + $cpu for more info on SMP. Uses a logarithmic scale (to see + small numbers) when you use the -l switch. Takes the switch '-t' + to use a temperature gradient, which makes the gradient values + change depending on the amplitude of a particular graph value + (try it and see). - color9 Change drawing color to color9 configuration option + curl url (interval_in_minutes) + Download data from URI using Curl at the specified interval. The + interval may be a floating point value greater than 0, otherwise + defaults to 15 minutes. Most useful when used in conjunction + with Lua and the Lua API. This object is threaded, and once a + thread is created it can't be explicitly destroyed. One thread + will run for each URI specified. You can use any protocol that + Curl supports. + desktop + Number of the desktop on which conky is running or the message + "Not running in X" if this is the case. + + + desktop_name + Name of the desktop on which conky is running or the message + "Not running in X" if this is the case. - cpu (cpuN) - CPU usage in percents. For SMP machines, the CPU number can be - provided as an argument. ${cpu cpu0} is the total usage, and - ${cpu cpuX} (X >= 1) are individual CPUs. + desktop_number + Number of desktops or the message "Not running in X" if this is + the case. - cpubar (cpu number) (height),(width) - Bar that shows CPU usage, height is bar's height in pixels. See - $cpu for more info on SMP. + disk_protect device + Disk protection status, if supported (needs kernel-patch). + Prints either "frozen" or "free " (note the padding). - cpugraph (cpu number) (height),(width) (gradient colour 1) (gradient - colour 2) - CPU usage graph, with optional colours in hex, minus the #. See - $cpu for more info on SMP. + diskio (device) + Displays current disk IO. Device is optional, and takes the form + of sda for /dev/sda. Individual partitions are allowed. - diskio Displays current disk IO. + diskio_read (device) + Displays current disk IO for reads. Device as in diskio. - diskiograph (height),(width) (gradient colour 1) (gradient colour 2) - (scale) - Disk IO graph, colours defined in hex, minus the #. If scale is - non-zero, it becomes the scale for the graph. + diskio_write (device) + Displays current disk IO for writes. Device as in diskio. - diskio_read - Displays current disk IO for reads. + diskiograph (device) (height),(width) (gradient colour 1) (gradient + colour 2) (scale) (-t) (-l) + Disk IO graph, colours defined in hex, minus the #. If scale is + non-zero, it becomes the scale for the graph. Uses a logarithmic + scale (to see small numbers) when you use -l switch. Takes the + switch '-t' to use a temperature gradient, which makes the gra- + dient values change depending on the amplitude of a particular + graph value (try it and see). - diskio_readgraph (height),(width) (gradient colour 1) (gradient colour - 2) (scale) - Disk IO graph for reads, colours defined in hex, minus the #. If - scale is non-zero, it becomes the scale for the graph. + diskiograph_read (device) (height),(width) (gradient colour 1) (gradi- + ent colour 2) (scale) (-t) (-l) + Disk IO graph for reads, colours defined in hex, minus the #. If + scale is non-zero, it becomes the scale for the graph. Device as + in diskio. Uses a logarithmic scale (to see small numbers) when + you use -l switch. Takes the switch '-t' to use a temperature + gradient, which makes the gradient values change depending on + the amplitude of a particular graph value (try it and see). - diskio_write - Displays current disk IO for writes. + diskiograph_write (device) (height),(width) (gradient colour 1) (gradi- + ent colour 2) (scale) (-t) (-l) + Disk IO graph for writes, colours defined in hex, minus the #. + If scale is non-zero, it becomes the scale for the graph. Device + as in diskio. Uses a logarithmic scale (to see small numbers) + when you use -l switch. Takes the switch '-t' to use a tempera- + ture gradient, which makes the gradient values change depending + on the amplitude of a particular graph value (try it and see). - diskio_writegraph (height),(width) (gradient colour 1) (gradient colour - 2) (scale) - Disk IO graph for writes, colours defined in hex, minus the #. - If scale is non-zero, it becomes the scale for the graph. + downspeed (net) + Download speed in suitable IEC units - downspeed net - Download speed in kilobytes + downspeedf (net) + Download speed in KiB with one decimal - downspeedf net - Download speed in kilobytes with one decimal + downspeedgraph (netdev) (height),(width) (gradient colour 1) (gradient + colour 2) (scale) (-t) (-l) + Download speed graph, colours defined in hex, minus the #. If + scale is non-zero, it becomes the scale for the graph. Uses a + logarithmic scale (to see small numbers) when you use -l switch. + Takes the switch '-t' to use a temperature gradient, which makes + the gradient values change depending on the amplitude of a par- + ticular graph value (try it and see). - downspeedgraph net (height),(width) (gradient colour 1) (gradient - colour 2) (scale) - Download speed graph, colours defined in hex, minus the #. If - scale is non-zero, it becomes the scale for the graph. + + draft_mails (maildir) (interval) + Number of mails marked as draft in the specified mailbox or mail + spool if not. Only maildir type mailboxes are supported, mbox + type will return -1. else Text to show if any of the above are not true + endif Ends an $if block. + + entropy_avail - Current entropy available for crypto freaks + Current entropy available for crypto freaks entropy_bar (height),(width) - Normalized bar of available entropy for crypto freaks + Normalized bar of available entropy for crypto freaks + + + entropy_perc + Percentage of entropy available in comparison to the poolsize entropy_poolsize - Total size of system entropy pool for crypto freaks + Total size of system entropy pool for crypto freaks + + + eval string + Evaluates given string according to the rules of TEXT interpre- + tation, i.e. parsing any contained text object specifications + into their output, any occuring '$$' into a single '$' and so + on. The output is then being parsed again. + + + eve api_userid api_key character_id + Fetches your currently training skill from the Eve Online API + servers (http://www.eve-online.com/) and displays the skill + along with the remaining training time. exec command - Executes a shell command and displays the output in conky. warn- - ing: this takes a lot more resources than other variables. I'd - recommend coding wanted behaviour in C and posting a patch. + Executes a shell command and displays the output in conky. warn- + ing: this takes a lot more resources than other variables. I'd + recommend coding wanted behaviour in C and posting a patch. execbar command - Same as exec, except if the first value return is a value be- - tween 0-100, it will use that number for a bar. The size for the - bar is currently fixed, but that may change in the future. + Same as exec, except if the first value return is a value be- + tween 0-100, it will use that number for a bar. The size for + bars can be controlled via the default_bar_size config setting. + + execgauge command + Same as exec, except if the first value returned is a value be- + tween 0-100, it will use that number for a gauge. The size for + gauges can be controlled via the default_gauge_size config set- + ting. - execgraph command - Same as execbar, but graphs values. + + execgraph (-t) (-l) command + Same as execbar, but graphs values. Uses a logaritmic scale when + the log option (-l switch) is given (to see small numbers). Val- + ues still have to be between 0 and 100. The size for graphs can + be controlled via the default_graph_size config setting. Takes + the switch '-t' to use a temperature gradient, which makes the + gradient values change depending on the amplitude of a particu- + lar graph value (try it and see). If -t or -l is your first ar- + gument, you may need to preceed it by a space (' '). execi interval command - Same as exec but with specific interval. Interval can't be less - than update_interval in configuration. See also $texeci + Same as exec but with specific interval. Interval can't be less + than update_interval in configuration. See also $texeci execibar interval command - Same as execbar, except with an interval + Same as execbar, except with an interval - execigraph interval command - Same as execigraph, but takes an interval arg graphs values + execigauge interval command + Same as execgauge, but takes an interval arg and gauges values. - font (font) - Specify a different font. This new font will apply to the cur- - rent line and everything following. You can use a $font with no - arguments to change back to the default font (much like with - $color) + execigraph interval (-t) (-l) command + Same as execgraph, but takes an interval arg and graphs values. + If -t or -l is your first argument, you may need to preceed it + by a space (' '). - freq (n) - Returns CPU #n's frequency in MHz. CPUs are counted from 1. If - omitted, the parameter defaults to 1. + execp command + Executes a shell command and displays the output in conky. warn- + ing: this takes a lot more resources than other variables. I'd + recommend coding wanted behaviour in C and posting a patch. This + differs from $exec in that it parses the output of the command, + so you can insert things like ${color red}hi!${color} in your + script and have it correctly parsed by Conky. Caveats: Conky + parses and evaluates the output of $execp every time Conky + loops, and then destroys all the objects. If you try to use any- + thing like $execi within an $execp statement, it will function- + ally run at the same interval that the $execp statement runs, as + it is created and destroyed at every interval. - freq_g (n) - Returns CPU #n's frequency in GHz. CPUs are counted from 1. If - omitted, the parameter defaults to 1. + execpi interval command + Same as execp but with specific interval. Interval can't be + less than update_interval in configuration. Note that the output + from the $execpi command is still parsed and evaluated at every + interval. + + + flagged_mails (maildir) (interval) + Number of mails marked as flagged in the specified mailbox or + mail spool if not. Only maildir type mailboxes are supported, + mbox type will return -1. - freq_dyn - Returns CPU frequency in MHz, but is calculated by counting to - clock cycles to complete an instruction. Only available for - x86/amd64. + font (font) + Specify a different font. This new font will apply to the cur- + rent line and everything following. You can use a $font with no + arguments to change back to the default font (much like with + $color) + + + format_time seconds format + Format time given in seconds. This var only works when the + times_in_seconds configuration setting is on. Format is a string + that should start and end with a "-char. The "-chars are not + part of the output, \w,\d,\h,\m,\s,\(,\) and \\ are replaced by + weeks,days,hours,minutes,seconds,(,) and \. If you leave out a + unit, it's value will be expressed in the highest unite lower + then the one left out. Text between ()-chars will not be visible + if a replaced unit in this text is 0. If seconds is a decimal + number then you can see the numbers behind the point by using \S + followed by a number that specifies the amount of digits behind + the point that you want to see (maximum 9). You can also place + a 'x' behind \S so you have all digits behind the point and no + trailing zero's. (also maximum 9) + + + forwarded_mails (maildir) (interval) + Number of mails marked as forwarded in the specified mailbox or + mail spool if not. Only maildir type mailboxes are supported, + mbox type will return -1. + + + freq (n) + Returns CPU #n's frequency in MHz. CPUs are counted from 1. If + omitted, the parameter defaults to 1. - freq_dyn_g - Returns CPU frequency in GHz, but is calculated by counting to - clock cycles to complete an instruction. Only available for - x86/amd64. + freq_g (n) + Returns CPU #n's frequency in GHz. CPUs are counted from 1. If + omitted, the parameter defaults to 1. fs_bar (height),(width) fs - Bar that shows how much space is used on a file system. height - is the height in pixels. fs is any file on that file system. + Bar that shows how much space is used on a file system. height + is the height in pixels. fs is any file on that file system. + + + fs_bar_free (height),(width) fs + Bar that shows how much space is free on a file system. height + is the height in pixels. fs is any file on that file system. fs_free (fs) - Free space on a file system available for users. + Free space on a file system available for users. fs_free_perc (fs) - Free percentage of space on a file system available for users. + Free percentage of space on a file system available for users. fs_size (fs) - File system size + File system size. + + + fs_type (fs) + File system type. fs_used (fs) - File system used space + File system used space. + + + fs_used_perc (fs) + Percent of file system used space. goto x The next element will be printed at position 'x'. - hddtemp dev, (host,(port)) - Displays temperature of a selected hard disk drive as reported - by the hddtemp daemon running on host:port. Default host is - 127.0.0.1, default port is 7634. + gw_iface + Displays the default route's interface or "multiple"/"none" ac- + cordingly. - head logfile lines (interval) - Displays first N lines of supplied text text file. If interval - is not supplied, Conky assumes 2x Conky's interval. Max of 30 - lines can be displayed, or until the text buffer is filled. + gw_ip Displays the default gateway's IP or "multiple"/"none" accord- + ingly. - hr (height) - Horizontal line, height is the height in pixels + hddtemp (dev) + Displays temperature of a selected hard disk drive as reported + by the hddtemp daemon. Use hddtemp_host and hddtemp_port to + specify a host and port for all hddtemp objects. If no dev pa- + rameter is given, the first disk returned by the hddtemp daemon + is used. - hwmon (dev) type n - Hwmon sensor from sysfs (Linux 2.6). Parameter dev may be omit- - ted if you have only one hwmon device. Parameter type is either - 'in' or 'vol' meaning voltage; 'fan' meaning fan; 'temp' (Cel- - sius) or 'tempf' (Fahrenheit) meaning temperature. Parameter n - is number of the sensor. See /sys/class/hwmon/ on your local - computer. + head logfile lines (next_check) + Displays first N lines of supplied text file. The file is + checked every 'next_check' update. If next_check is not sup- + plied, Conky defaults to 2. Max of 30 lines can be displayed, or + until the text buffer is filled. - iconv_start codeset_from codeset_to - Convert text from one codeset to another using GNU iconv. Needs - to be stopped with iconv_stop. + hr (height) + Horizontal line, height is the height in pixels - iconv_stop - Stop iconv codeset conversion. + hwmon (dev) type n (factor offset) + Hwmon sensor from sysfs (Linux 2.6). Parameter dev may be omit- + ted if you have only one hwmon device. Parameter type is either + 'in' or 'vol' meaning voltage; 'fan' meaning fan; 'temp' meaning + temperature. Parameter n is number of the sensor. See + /sys/class/hwmon/ on your local computer. The optional arguments + 'factor' and 'offset' allow precalculation of the raw input, + which is being modified as follows: 'input = input * factor + + offset'. Note that they have to be given as decimal values (i.e. + contain at least one decimal place). - i2c (dev) type n - I2C sensor from sysfs (Linux 2.6). Parameter dev may be omitted - if you have only one I2C device. Parameter type is either 'in' - or 'vol' meaning voltage; 'fan' meaning fan; 'temp' (Celsius) or - 'tempf' (Fahrenheit) meaning temperature. Parameter n is number - of the sensor. See /sys/bus/i2c/devices/ on your local computer. + i2c (dev) type n (factor offset) + I2C sensor from sysfs (Linux 2.6). Parameter dev may be omitted + if you have only one I2C device. Parameter type is either 'in' + or 'vol' meaning voltage; 'fan' meaning fan; 'temp' meaning tem- + perature. Parameter n is number of the sensor. See + /sys/bus/i2c/devices/ on your local computer. The optional argu- + ments 'factor' and 'offset' allow precalculation of the raw in- + put, which is being modified as follows: 'input = input * factor + + offset'. Note that they have to be given as decimal values + (i.e. contain at least one decimal place). i8k_ac_status - If running the i8k kernel driver for Inspiron laptops, displays - whether ac power is on, as listed in /proc/i8k (translated to - human-readable). Beware that this is by default not enabled by - i8k itself. + If running the i8k kernel driver for Inspiron laptops, displays + whether ac power is on, as listed in /proc/i8k (translated to + human-readable). Beware that this is by default not enabled by + i8k itself. i8k_bios - If running the i8k kernel driver for Inspiron laptops, displays - the bios version as listed in /proc/i8k. + If running the i8k kernel driver for Inspiron laptops, displays + the bios version as listed in /proc/i8k. i8k_buttons_status - If running the i8k kernel driver for Inspiron laptops, displays - the volume buttons status as listed in /proc/i8k. + If running the i8k kernel driver for Inspiron laptops, displays + the volume buttons status as listed in /proc/i8k. i8k_cpu_temp - If running the i8k kernel driver for Inspiron laptops, displays - the cpu temperature in Celsius, as reported by /proc/i8k. - - - i8k_cpu_tempf - If running the i8k kernel driver for Inspiron laptops, displays - the cpu temperature in Fahrenheit, as reported by /proc/i8k. + If running the i8k kernel driver for Inspiron laptops, displays + the cpu temperature in Celsius, as reported by /proc/i8k. i8k_left_fan_rpm - If running the i8k kernel driver for Inspiron laptops, displays - the left fan's rate of rotation, in revolutions per minute as - listed in /proc/i8k. Beware, some laptops i8k reports these fans - in reverse order. + If running the i8k kernel driver for Inspiron laptops, displays + the left fan's rate of rotation, in revolutions per minute as + listed in /proc/i8k. Beware, some laptops i8k reports these fans + in reverse order. i8k_left_fan_status - If running the i8k kernel driver for Inspiron laptops, displays - the left fan status as listed in /proc/i8k (translated to human- - readable). Beware, some laptops i8k reports these fans in re- - verse order. + If running the i8k kernel driver for Inspiron laptops, displays + the left fan status as listed in /proc/i8k (translated to human- + readable). Beware, some laptops i8k reports these fans in re- + verse order. i8k_right_fan_rpm - If running the i8k kernel driver for Inspiron laptops, displays - the right fan's rate of rotation, in revolutions per minute as - listed in /proc/i8k. Beware, some laptops i8k reports these fans - in reverse order. + If running the i8k kernel driver for Inspiron laptops, displays + the right fan's rate of rotation, in revolutions per minute as + listed in /proc/i8k. Beware, some laptops i8k reports these fans + in reverse order. i8k_right_fan_status - If running the i8k kernel driver for Inspiron laptops, displays - the right fan status as listed in /proc/i8k (translated to hu- - man-readable). Beware, some laptops i8k reports these fans in - reverse order. + If running the i8k kernel driver for Inspiron laptops, displays + the right fan status as listed in /proc/i8k (translated to hu- + man-readable). Beware, some laptops i8k reports these fans in + reverse order. i8k_serial - If running the i8k kernel driver for Inspiron laptops, displays - your laptop serial number as listed in /proc/i8k. + If running the i8k kernel driver for Inspiron laptops, displays + your laptop serial number as listed in /proc/i8k. i8k_version - If running the i8k kernel driver for Inspiron laptops, displays - the version formatting of /proc/i8k. + If running the i8k kernel driver for Inspiron laptops, displays + the version formatting of /proc/i8k. + + + ibm_brightness + If running the IBM ACPI, displays the brigtness of the laptops's + LCD (0-7). ibm_fan - If running the IBM ACPI, displays the fan speed. + If running the IBM ACPI, displays the fan speed. ibm_temps N - If running the IBM ACPI, displays the temperatures from the IBM - temperature sensors (N=0..7) Sensor 0 is on the CPU, 3 is on the - GPU. + If running the IBM ACPI, displays the temperatures from the IBM + temperature sensors (N=0..7) Sensor 0 is on the CPU, 3 is on the + GPU. ibm_volume - If running the IBM ACPI, displays the "master" volume, con- - trolled by the volume keys (0-14). + If running the IBM ACPI, displays the "master" volume, con- + trolled by the volume keys (0-14). - ibm_brightness - If running the IBM ACPI, displays the brigtness of the laptops's - LCD (0-7). + iconv_start codeset_from codeset_to + Convert text from one codeset to another using GNU iconv. Needs + to be stopped with iconv_stop. - if_empty (var) - if conky variable VAR is empty, display everything between - $if_empty and the matching $endif + iconv_stop + Stop iconv codeset conversion. - if_running (process) - if PROCESS is running, display everything $if_running and the - matching $endif + if_empty (var) + if conky variable VAR is empty, display everything between + $if_empty and the matching $endif if_existing file (string) - if FILE exists, display everything between if_existing and the - matching $endif. The optional second paramater checks for FILE - containing the specified string and prints everything between - $if_existing and the matching $endif. + if FILE exists, display everything between if_existing and the + matching $endif. The optional second paramater checks for FILE + containing the specified string and prints everything between + $if_existing and the matching $endif. - if_mounted (mountpoint) - if MOUNTPOINT is mounted, display everything between $if_mounted - and the matching $endif + if_gw if there is at least one default gateway, display everything be- + tween $if_gw and the matching $endif - imap_messages (args) - Displays the number of messages in your global IMAP inbox by de- - fault. You can define individual IMAP inboxes seperately by - passing arguments to this object. Arguments are: "host user pass - [-i interval] [-p port] [-e command]". Default port is 143, de- - fault interval is 5 minutes. If the password is supplied as '*', - you will be prompted to enter the password when Conky starts. + if_match expression + Evaluates the given boolean expression, printing everything be- + tween $if_match and the matching $endif depending on whether the + evaluation returns true or not. Valid expressions consist of a + left side, an operator and a right side. Left and right sides + are being parsed for contained text objects before evaluation. + Recognised left and right side types are: + doubleArgument consists of only digits and a single dot. + longArgument consists of only digits. + stringArgument is enclosed in quotation marks (") - imap_unseen (args) - Displays the number of unseen messages in your global IMAP inbox - by default. You can define individual IMAP inboxes seperately by - passing arguments to this object. Arguments are: "host user pass - [-i interval] [-p port] [-e command]". Default port is 143, de- - fault interval is 5 minutes. If the password is supplied as '*', - you will be prompted to enter the password when Conky starts. + Valid operands are: '>', '<', '>=', '<=', '==', '!='. - kernel Kernel version + if_mixer_mute (mixer) + If mixer exists, display everything between $if_mixer_mute and + the matching $endif. If no mixer is specified, "Master" is used. - loadavg - (1,2,3)> System load average, 1 is for past 1 minute, 2 for past - 5 minutes and 3 for past 15 minutes. + if_mounted (mountpoint) + if MOUNTPOINT is mounted, display everything between $if_mounted + and the matching $endif - machine - Machine, i686 for example + if_mpd_playing + if mpd is playing or paused, display everything between + $if_mpd_playing and the matching $endif - mails Mail count in mail spool. You can use program like fetchmail to - get mails from some server using your favourite protocol. See - also new_mails. + if_running (process) + if PROCESS is running, display everything $if_running and the + matching $endif. This uses the ``pidof'' command, so the -x + switch is also supported. - mboxscan (-n number of messages to print) (-fw from width) (-sw subject - width) mbox - Print a summary of recent messages in an mbox format mailbox. - mbox parameter is the filename of the mailbox (can be encapsu- - lated using '"', ie. ${mboxscan -n 10 "/home/brenden/some box"} + if_smapi_bat_installed (INDEX) + when using smapi, if the battery with index INDEX is installed, + display everything between $if_smapi_bat_installed and the + matching $endif - mem Amount of memory in use + if_up (interface) + if INTERFACE exists and is up, display everything between $if_up + and the matching $endif - membar (height),(width) - Bar that shows amount of memory in use + if_updatenr (updatenr) + If it's the UPDATENR-th time that conky updates, display every- + thing between $if_updatenr and the matching $endif. The counter + resets when the highest UPDATENR is reached. Example : "{$if_up- + datenr 1}foo$endif{$if_updatenr 2}bar$endif{$if_updatenr 4}$en- + dif" shows foo 25% of the time followed by bar 25% of the time + followed by nothing the other half of the time. - memmax Total amount of memory + if_xmms2_connected + Display everything between $if_xmms2_connected and the matching + $endif if xmms2 is running. - memperc - Percentage of memory in use + image (-p x,y) (-s WxH) (-n) (-f interval) + Renders an image from the path specified using Imlib2. Takes 4 + optional arguments: a position, a size, a no-cache switch, and a + cache flush interval. Changing the x,y position will move the + position of the image, and changing the WxH will scale the im- + age. If you specify the no-cache flag (-n), the image will not + be cached. Alternately, you can specify the -f int switch to + specify a cache flust interval for a particular image. Example: + ${image /home/brenden/cheeseburger.jpg -p 20,20 -s 200x200} will + render 'cheeseburger.jpg' at (20,20) scaled to 200x200 pixels. + Conky does not make any attempt to adjust the position (or any + other formatting) of images, they are just rendered as per the + arguments passed. The only reason $image is part of the TEXT + section, is to allow for runtime modifications, through $execp + $lua_parse, or some other method. - mpd_artist - Artist in current MPD song must be enabled at compile + imap_messages (args) + Displays the number of messages in your global IMAP inbox by de- + fault. You can define individual IMAP inboxes separately by + passing arguments to this object. Arguments are: "host user + pass [-i interval (in seconds)] [-f 'folder'] [-p port] [-e + 'command'] [-r retries]". Default port is 143, default folder is + 'INBOX', default interval is 5 minutes, and default number of + retries before giving up is 5. If the password is supplied as + '*', you will be prompted to enter the password when Conky + starts. - mpd_album - Album in current MPD song + imap_unseen (args) + Displays the number of unseen messages in your global IMAP inbox + by default. You can define individual IMAP inboxes separately by + passing arguments to this object. Arguments are: "host user pass + [-i interval (in seconds)] [-f 'folder'] [-p port] [-e 'com- + mand'] [-r retries]". Default port is 143, default folder is + 'INBOX', default interval is 5 minutes, and default number of + retries before giving up is 5. If the password is supplied as + '*', you will be prompted to enter the password when Conky + starts. - mpd_bar (height),(width) - Bar of mpd's progress + include path + Loads the configfile at path, places the configsettings behind + the configsettings in the orginal config and places the vars + where the includevar stood. + ioscheduler disk + Prints the current ioscheduler used for the given disk name + (i.e. e.g. "hda" or "sdb") - mpd_bitrate - Bitrate of current song + kernel Kernel version - mpd_status - Playing, stopped, et cetera. + laptop_mode + The value of /proc/sys/vm/laptop_mode - mpd_title (max length) - Title of current MPD song + lines textfile + Displays the number of lines in the given file - mpd_vol - MPD's volume + loadavg (1|2|3) + System load average, 1 is for past 1 minute, 2 for past 5 min- + utes and 3 for past 15 minutes. Without argument, prints all + three values separated by whitespace. - mpd_elapsed - Song's elapsed time + loadgraph (height),(width) (gradient colour 1) (gradient colour 2) + (scale) (-t) (-l) + Load1 average graph, similar to xload, with optional colours in + hex, minus the #. Uses a logarithmic scale (to see small num- + bers) when you use the -l switch. Takes the switch '-t' to use + a temperature gradient, which makes the gradient values change + depending on the amplitude of a particular graph value (try it + and see). - mpd_length - Song's length + lua function_name (function parameters) + Executes a Lua function with given parameters, then prints the + returned string. See also 'lua_load' on how to load scripts. + Conky puts 'conky_' in front of function_name to prevent acci- + dental calls to the wrong function unless you put you place + 'conky_' in front of it yourself. - mpd_percent - Percent of song's progress + lua_bar (height, width) function_name (function parameters) + Executes a Lua function with given parameters and draws a bar. + Expects result value to be an integer between 0 and 100. See al- + so 'lua_load' on how to load scripts. Conky puts 'conky_' in + front of function_name to prevent accidental calls to the wrong + function unless you put you place 'conky_' in front of it your- + self. - mpd_random - Random status (On/Off) + lua_gauge (height, width) function_name (function parameters) + Executes a Lua function with given parameters and draws a gauge. + Expects result value to be an integer between 0 and 100. See al- + so 'lua_load' on how to load scripts. Conky puts 'conky_' in + front of function_name to prevent accidental calls to the wrong + function unless you put you place 'conky_' in front of it your- + self. - mpd_repeat - Repeat status (On/Off) + lua_graph function_name (height),(width) (gradient colour 1) (gradient + colour 2) (scale) (-t) (-l) + Executes a Lua function with and draws a graph. Expects result + value to be any number, and by default will scale to show the + full range. See also 'lua_load' on how to load scripts. Takes + the switch '-t' to use a temperature gradient, which makes the + gradient values change depending on the amplitude of a particu- + lar graph value (try it and see). Conky puts 'conky_' in front + of function_name to prevent accidental calls to the wrong func- + tion unless you put you place 'conky_' in front of it yourself. - mpd_track - Prints the MPD track field + lua_parse function_name (function parameters) + Executes a Lua function with given parameters as per $lua, then + parses and prints the result value as per the syntax for Conky's + TEXT section. See also 'lua_load' on how to load scripts. Conky + puts 'conky_' in front of function_name to prevent accidental + calls to the wrong function unless you put you place 'conky_' in + front of it yourself. - mpd_name - Prints the MPD name field + machine + Machine, i686 for example - mpd_file - Prints the file name of the current MPD song + mails (mailbox) (interval) + Mail count in the specified mailbox or your mail spool if not. + Both mbox and maildir type mailboxes are supported. You can use + a program like fetchmail to get mails from some server using + your favourite protocol. See also new_mails. - mpd_smart - Prints the song name in either the form "artist - title" or file - name, depending on whats available + mboxscan (-n number of messages to print) (-fw from width) (-sw subject + width) mbox + Print a summary of recent messages in an mbox format mailbox. + mbox parameter is the filename of the mailbox (can be encapsu- + lated using '"', ie. ${mboxscan -n 10 "/home/brenden/some box"} - new_mails - Unread mail count in mail spool. + mem Amount of memory in use - nodename - Hostname + membar (height),(width) + Bar that shows amount of memory in use - outlinecolor (color) - Change outline color + memeasyfree + Amount of free memory including the memory that is very easily + freed (buffers/cache) - pb_battery item - If running on Apple powerbook/ibook, display information on bat- - tery status. The item parameter specifies, what information to - display. Exactly one item must be specified. Valid items are: - - status: Display if battery is fully charged, charging, discharg- - ing or absent (running on AC) - percent: Display charge of battery in percent, if charging or - discharging. Nothing will be displayed, if battery is fully - charged or absent. - time: Display the time remaining until the battery will be fully - charged or discharged at current rate. Nothing is displayed, if - battery is absent or if it's present but fully charged and not - discharging. - - - platform (dev) type n - Platform sensor from sysfs (Linux 2.6). Parameter dev may be - omitted if you have only one platform device. Platform type is - either 'in' or 'vol' meaning voltage; 'fan' meaning fan; 'temp' - (Celsius) or 'tempf' (Fahrenheit) meaning temperature. Parameter - n is number of the sensor. See /sys/bus/platform/devices/ on - your local computer. + memfree + Amount of free memory - pop3_unseen (args) - Displays the number of unseen messages in your global POP3 inbox - by default. You can define individual POP3 inboxes seperately by - passing arguments to this object. Arguments are: "host user pass - [-i interval] [-p port] [-e command]". Default port is 110, de- - fault interval is 5 minutes. If the password is supplied as '*', - you will be prompted to enter the password when Conky starts. + memgauge (height),(width) + Gauge that shows amount of memory in use (see cpugauge) - pop3_used (args) - Displays the amount of space (in MiB, 2^20) used in your global - POP3 inbox by default. You can define individual POP3 inboxes - seperately by passing arguments to this object. Arguments are: - "host user pass [-i interval] [-p port] [-e command]". Default - port is 110, default interval is 5 minutes. If the password is - supplied as '*', you will be prompted to enter the password when - Conky starts. + memgraph (height),(width) (gradient colour 1) (gradient colour 2) + (scale) (-t) (-l) + Memory usage graph. Uses a logarithmic scale (to see small num- + bers) when you use the -l switch. Takes the switch '-t' to use a + temperature gradient, which makes the gradient values change de- + pending on the amplitude of a particular graph value (try it and + see). - pre_exec shell command - Executes a shell command one time before conky displays anything - and puts output as text. + memmax Total amount of memory - processes - Total processes (sleeping and running) + memperc + Percentage of memory in use - running_processes - Running processes (not sleeping), requires Linux 2.6 + mixer (device) + Prints the mixer value as reported by the OS. Default mixer is + "Master", but you can specify one of the available ALSA Simple + mixer controls. You can find the list of those available on + your system using amixer. - shadecolor (color) - Change shading color + mixerbar (device) + Displays mixer value in a bar as reported by the OS. See docs + for $mixer for details on arguments. - stippled_hr (space) - Stippled (dashed) horizontal line + mixerl (device) + Prints the left channel mixer value as reported by the OS. See + docs for $mixer for details on arguments. - swapbar (height),(width) - Bar that shows amount of swap in use + mixerlbar (device) + Displays the left channel mixer value in a bar as reported by + the OS. See docs for $mixer for details on arguments. - swap Amount of swap in use + mixerr (device) + Prints the right channel mixer value as reported by the OS. See + docs for $mixer for details on arguments. - swapmax - Total amount of swap + mixerrbar (device) + Displays the right channel mixer value in a bar as reported by + the OS. See docs for $mixer for details on arguments. - swapperc - Percentage of swap in use + moc_album + Album of the current MOC song - sysname - System name, Linux for example - - - tcp_portmon port_begin port_end item (index) (ip4 only at present) - TCP port monitor for specified local ports. Port numbers must be - in the range 1 to 65535. Valid items are: - - count - total number of connections in the range - rip - remote ip address - rhost - remote host name - rport - remote port number - rservice - remote service name from /etc/services - lip - local ip address - lhost - local host name - lport - local port number - lservice - local service name from /etc/services - - The connection index provides you with access to each connection - in the port monitor. The monitor will return information for in- - dex values from 0 to n-1 connections. Values higher than n-1 are - simply ignored. For the "count" item, the connection index must - be omitted. It is required for all other items. - - Examples: - ${tcp_portmon 6881 6999 count} - displays the number of connec- - tions in the bittorrent port range - ${tcp_portmon 22 22 rip 0} - displays the remote host ip of the - first sshd connection - ${tcp_portmon 22 22 rip 9} - displays the remote host ip of the - tenth sshd connection - ${tcp_portmon 1 1024 rhost 0} - displays the remote host name of - the first connection on a privileged port - ${tcp_portmon 1 1024 rport 4} - displays the remote host port of - the fifth connection on a privileged port - ${tcp_portmon 1 65535 lservice 14} - displays the local service - name of the fifteenth connection in the range of all ports - - Note that port monitor variables which share the same port range - actually refer to the same monitor, so many references to a sin- - gle port range for different items and different indexes all use - the same monitor internally. In other words, the program avoids - creating redundant monitors. - texeci interval command - Runs a command at an interval inside a thread and displays the - output. Same as $execi, except the command is run inside a - thread. Use this if you have a slow script to keep Conky updat- - ing. You should make the interval slightly longer then the time - it takes your script to execute. For example, if you have a - script that take 5 seconds to execute, you should make the in- - terval at least 6 seconds. See also $execi. + moc_artist + Artist of the current MOC song + + + moc_bitrate + Bitrate in the current MOC song + + + moc_curtime + Current time of the current MOC song + + + moc_file + File name of the current MOC song + + + moc_rate + Rate of the current MOC song + + + moc_song + The current song name being played in MOC. + + + moc_state + Current state of MOC; playing, stopped etc. + + + moc_timeleft + Time left in the current MOC song + + + moc_title + Title of the current MOC song + + + moc_totaltime + Total length of the current MOC song + + + monitor + Number of the monitor on which conky is running or the message + "Not running in X" if this is the case. + + + monitor_number + Number of monitors or the message "Not running in X" if this is + the case. + + + mpd_album + Album in current MPD song + + + mpd_artist + Artist in current MPD song must be enabled at compile + + + mpd_bar (height),(width) + Bar of mpd's progress + + + mpd_bitrate + Bitrate of current song + + + mpd_elapsed + Song's elapsed time + + + mpd_file + Prints the file name of the current MPD song + + + mpd_length + Song's length + + + mpd_name + Prints the MPD name field + + + mpd_percent + Percent of song's progress + + + mpd_random + Random status (On/Off) + + + mpd_repeat + Repeat status (On/Off) + + + mpd_smart (max length) + Prints the song name in either the form "artist - title" or file + name, depending on whats available + + + mpd_status + Playing, stopped, et cetera. + + + mpd_title (max length) + Title of current MPD song + + + mpd_track + Prints the MPD track field + + + mpd_vol + MPD's volume + + + nameserver (index) + Print a nameserver from /etc/resolv.conf. Index starts at and + defaults to 0. + + + new_mails (mailbox) (interval) + Unread mail count in the specified mailbox or mail spool if not. + Both mbox and maildir type mailboxes are supported. + + + nodename + Hostname + + + nvidia threshold temp ambient gpufreq memfreq imagequality + Nvidia graficcard support for the XNVCtrl library. Each option + can be shortened to the least significant part. Temperatures are + printed as float, all other values as integer. + + threshold The thresholdtemperature at which the gpu slows down + temp Gives the gpu current temperature + ambient Gives current air temperature near GPU case + gpufreq Gives the current gpu frequency + memfreq Gives the current mem frequency + imagequality Which imagequality should be chosen by OpenGL ap- + plications offset (pixels) - Move text over by N pixels. See also $voffset. + Move text over by N pixels. See also $voffset. + + + outlinecolor (color) + Change outline color + + + pb_battery item + If running on Apple powerbook/ibook, display information on bat- + tery status. The item parameter specifies, what information to + display. Exactly one item must be specified. Valid items are: + + status Display if battery is fully charged, charging, discharg- + ing or absent (running on AC) + percent Display charge of battery in percent, if charging or + discharging. Nothing will be displayed, if battery is fully + charged or absent. + time Display the time remaining until the battery will be fully + charged or discharged at current rate. Nothing is displayed, if + battery is absent or if it's present but fully charged and not + discharging. + + + pid_chroot pid + Directory used as rootdirectory by the process (this will be "/" + unless the process did a chroot syscall) + + + pid_cmdline pid + Command line this process was invoked with + + + pid_cwd pid + Current working directory of the process + + + pid_environ pid varname + Contents of a environment-var of the process + + + pid_environ_list pid + List of environment-vars that the process can see + + + pid_exe pid + Path to executed command that started the process + + + pid_nice pid + The nice value of the process + + + pid_openfiles pid + List of files that the process has open + + + pid_parent pid + The pid of the parent of the process + + + pid_priority pid + The priority of the process (see 'priority' in "man 5 proc") + + + pid_read pid + Total number of bytes read by the process + + + pid_state pid + State of the process + + + pid_state_short pid + One of the chars in "RSDZTW" representing the state of the + process where R is running, S is sleeping in an interruptible + wait, D is waiting in uninterruptible disk sleep, Z is zombie, T + is traced or stopped (on a signal), and W is paging + + + pid_stderr pid + Filedescriptor binded to the STDERR of the process + + + pid_stdin pid + Filedescriptor binded to the STDIN of the process + + + pid_stdout pid + Filedescriptor binded to the STDOUT of the process + + + pid_threads pid + Number of threads in process containing this thread + + + pid_thread_list pid + List with pid's from threads from this process + + + pid_time_kernelmode pid + Amount of time that the process has been scheduled in kernel + mode in seconds + + + pid_time_usermode pid + Amount of time that the process has been scheduled in user mode + in seconds + + + pid_time pid + Sum of $pid_time_kernelmode and $pid_time_usermode + + + pid_uid pid + The real uid of the process + + + pid_euid pid + The effective uid of the process + + + pid_suid pid + The saved set uid of the process + + + pid_fsuid pid + The file system uid of the process + + + pid_gid pid + The real gid of the process + + + pid_egid pid + The effective gid of the process + + + pid_sgid pid + The saved set gid of the process + + + pid_fsgid pid + The file system gid of the process + + + pid_vmpeak pid + Peak virtual memory size of the process + + + pid_vmsize pid + Virtual memory size of the process + + + pid_vmlck pid + Locked memory size of the process + + + pid_vmhwm pid + Peak resident set size ("high water mark") of the process + + + pid_vmrss pid + Resident set size of the process + + + pid_vmdata pid + Data segment size of the process + + + pid_vmstk pid + Stack segment size of the process + + pid_vmexe pid + Text segment size of the process - rss url delay_in_minutes action item_num - Download and parse RSS feeds. Action may be one of the follow- - ing: feed_title, item_title (with num par), item_desc (with num - par) and item_titles. + + pid_vmlib pid + Shared library code size of the process + + + pid_vmpte pid + Page table entries size of the process + + + pid_write pid + Total number of bytes written by the process + + + platform (dev) type n (factor offset) + Platform sensor from sysfs (Linux 2.6). Parameter dev may be + omitted if you have only one platform device. Platform type is + either 'in' or 'vol' meaning voltage; 'fan' meaning fan; 'temp' + meaning temperature. Parameter n is number of the sensor. See + /sys/bus/platform/devices/ on your local computer. The optional + arguments 'factor' and 'offset' allow precalculation of the raw + input, which is being modified as follows: 'input = input * fac- + tor + offset'. Note that they have to be given as decimal values + (i.e. contain at least one decimal place). + + + pop3_unseen (args) + Displays the number of unseen messages in your global POP3 inbox + by default. You can define individual POP3 inboxes separately by + passing arguments to this object. Arguments are: "host user pass + [-i interval (in seconds)] [-p port] [-e 'command'] [-r re- + tries]". Default port is 110, default interval is 5 minutes, and + default number of retries before giving up is 5. If the password + is supplied as '*', you will be prompted to enter the password + when Conky starts. + + + pop3_used (args) + Displays the amount of space (in MiB, 2^20) used in your global + POP3 inbox by default. You can define individual POP3 inboxes + separately by passing arguments to this object. Arguments are: + "host user pass [-i interval (in seconds)] [-p port] [-e 'com- + mand'] [-r retries]". Default port is 110, default interval is 5 + minutes, and default number of retries before giving up is 5. If + the password is supplied as '*', you will be prompted to enter + the password when Conky starts. + + + pre_exec shell command + Executes a shell command one time before conky displays anything + and puts output as text. + + + processes + Total processes (sleeping and running) + + + read_tcp (host) port + Connects to a tcp port on a host (default is localhost), reads + every char available at the moment and shows them. + + + replied_mails (maildir) (interval) + Number of mails marked as replied in the specified mailbox or + mail spool if not. Only maildir type mailboxes are supported, + mbox type will return -1. + + + rss uri interval_in_minutes action (num_par (spaces_in_front)) + Download and parse RSS feeds. The interval may be a floating + point value greater than 0, otherwise defaults to 15 minutes. + Action may be one of the following: feed_title, item_title (with + num par), item_desc (with num par) and item_titles (when using + this action and spaces_in_front is given conky places that many + spaces in front of each item). This object is threaded, and once + a thread is created it can't be explicitly destroyed. One thread + will run for each URI specified. You can use any protocol that + Curl supports. + + running_processes + Running processes (not sleeping), requires Linux 2.6 + + + running_threads + Number of running (runnable) threads. Linux only. + + + scroll length (step) text + Scroll 'text' by 'step' characters showing 'length' number of + characters at the same time. The text may also contain vari- + ables. 'step' is optional and defaults to 1 if not set. If a var + creates output on multiple lines then the lines are placed be- + hind each other separated with a '|'-sign. If you change the + textcolor inside $scroll it will automatically have it's old + value back at the end of $scroll. The end and the start of text + will be separated by 'length' number of spaces. + + + seen_mails (maildir) (interval) + Number of mails marked as seen in the specified mailbox or mail + spool if not. Only maildir type mailboxes are supported, mbox + type will return -1. + + + shadecolor (color) + Change shading color + + + smapi (ARGS) + when using smapi, display contents of the /sys/devices/plat- + form/smapi directory. ARGS are either '(FILENAME)' or 'bat (IN- + DEX) (FILENAME)' to display the corresponding files' content. + This is a very raw method of accessing the smapi values. When + available, better use one of the smapi_* variables instead. + + + smapi_bat_bar (INDEX),(height),(width) + when using smapi, display the remaining capacity of the battery + with index INDEX as a bar. + + + smapi_bat_perc (INDEX) + when using smapi, display the remaining capacity in percent of + the battery with index INDEX. This is a separate variable be- + cause it supports the 'use_spacer' configuration option. + + + smapi_bat_power INDEX + when using smapi, display the current power of the battery with + index INDEX in watt. This is a separate variable because the + original read out value is being converted from mW. The sign of + the output reflects charging (positive) or discharging (nega- + tive) state. + + + smapi_bat_temp INDEX + when using smapi, display the current temperature of the battery + with index INDEX in degree Celsius. This is a separate variable + because the original read out value is being converted from mil- + li degree Celsius. + + + sony_fanspeed + Displays the Sony VAIO fanspeed information if sony-laptop ker- + nel support is enabled. Linux only. + + + stippled_hr (space) + Stippled (dashed) horizontal line + + + swap Amount of swap in use + + + swapbar (height),(width) + Bar that shows amount of swap in use + + + swapfree + Amount of free swap + + + swapmax + Total amount of swap + + + swapperc + Percentage of swap in use + + + sysname + System name, Linux for example tab (width, (start)) - Puts a tab of the specified width, starting from column 'start'. + Puts a tab of the specified width, starting from column 'start'. + The unit is pixels for both arguments. + + + tail logfile lines (next_check) + Displays last N lines of supplied text file. The file is checked + every 'next_check' update. If next_check is not supplied, Conky + defaults to 2. Max of 30 lines can be displayed, or until the + text buffer is filled. + + + tcp_portmon port_begin port_end item (index) + TCP port (both IPv6 and IPv4) monitor for specified local ports. + Port numbers must be in the range 1 to 65535. Valid items are: + + count Total number of connections in the range + rip Remote ip address + rhost Remote host name + rport Remote port number + rservice Remote service name from /etc/services + lip Local ip address + lhost Local host name + lport Local port number + lservice Local service name from /etc/services + + The connection index provides you with access to each connection + in the port monitor. The monitor will return information for in- + dex values from 0 to n-1 connections. Values higher than n-1 are + simply ignored. For the "count" item, the connection index must + be omitted. It is required for all other items. + + Examples: + + ${tcp_portmon 6881 6999 count} Displays the number of connec- + tions in the bittorrent port range + ${tcp_portmon 22 22 rip 0} Displays the remote host ip of the + first sshd connection + ${tcp_portmon 22 22 rip 9} Displays the remote host ip of the + tenth sshd connection + ${tcp_portmon 1 1024 rhost 0} Displays the remote host name of + the first connection on a privileged port + ${tcp_portmon 1 1024 rport 4} Displays the remote host port of + the fifth connection on a privileged port + ${tcp_portmon 1 65535 lservice 14} Displays the local service + name of the fifteenth connection in the range of all ports + + Note that port monitor variables which share the same port range + actually refer to the same monitor, so many references to a sin- + gle port range for different items and different indexes all use + the same monitor internally. In other words, the program avoids + creating redundant monitors. + + templateN (arg1) (arg2) (arg3 ...) + Evaluate the content of the templateN configuration variable + (where N is a value between 0 and 9, inclusively), applying sub- + stitutions as described in the documentation of the correspond- + ing configuration variable. The number of arguments is optional, + but must match the highest referred index in the template. You + can use the same special sequences in each argument as the ones + valid for a template definition, e.g. to allow an argument to + contain a whitespace. Also simple nesting of templates is possi- + ble this way. + + Here are some examples of template definitions: + + template0 $\1\2 + template1 \1: ${fs_used \2} / ${fs_size \2} + template2 \1 \2 + + The following list shows sample usage of the templates defined + above, with the equivalent syntax when not using any template at + all: + + using template same without template + ”””””””””””””””””””””””””””””””””””””””””””””””””””””””” + ${template0 node name} $nodename + ${template1 root /} root: ${fs_free /} / + ${fs_size /} + ${template1 ${template2\ disk root: ${fs_free /} / + disk\ root} /} ${fs_size /} + + texeci interval command + Runs a command at an interval inside a thread and displays the + output. Same as $execi, except the command is run inside a + thread. Use this if you have a slow script to keep Conky updat- + ing. You should make the interval slightly longer then the time + it takes your script to execute. For example, if you have a + script that take 5 seconds to execute, you should make the in- + terval at least 6 seconds. See also $execi. This object will + clean up the thread when it is destroyed, so it can safely be + used in a nested fashion, though it may not produce the desired + behaviour if used this way. - tail logfile lines (interval) - Displays last N lines of supplied text text file. If interval is - not supplied, Conky assumes 2x Conky's interval. Max of 30 lines - can be displayed, or until the text buffer is filled. + threads + Total threads time (format) - Local time, see man strftime to get more information about for- - mat + Local time, see man strftime to get more information about for- + mat - utime (format) - Display time in UTC (universal coordinate time). + to_bytes size + If 'size' is a number followed by a size-unit (kilo- + byte,mb,GiB,...) then it converts the size to bytes and shows it + without unit, otherwise it just shows 'size'. + + + top type num + This takes arguments in the form:top (name) (number) Basically, + processes are ranked from highest to lowest in terms of cpu us- + age, which is what (num) represents. The types are: "name", + "pid", "cpu", "mem", "mem_res", "mem_vsize", "time", "io_perc", + "io_read" and "io_write". There can be a max of 10 processes + listed. + + + top_io type num + Same as top, except sorted by the amount of I/O the process has + done during the update interval + + + top_mem type num + Same as top, except sorted by mem usage instead of cpu + + + top_time type num + Same as top, except sorted by total CPU time instead of current + CPU usage + + totaldown (net) + Total download, overflows at 4 GB on Linux with 32-bit arch and + there doesn't seem to be a way to know how many times it has al- + ready done that before conky has started. - tztime (timezone) (format) - Local time for specified timezone, see man strftime to get more - information about format. The timezone argument is specified in - similar fashion as TZ environment variable. For hints, look in - /usr/share/zoneinfo. e.g. US/Pacific, Europe/Zurich, etc. + totalup (net) + Total upload, this one too, may overflow - totaldown net - Total download, overflows at 4 GB on Linux with 32-bit arch and - there doesn't seem to be a way to know how many times it has al- - ready done that before conky has started. + trashed_mails (maildir) (interval) + Number of mails marked as trashed in the specified mailbox or + mail spool if not. Only maildir type mailboxes are supported, + mbox type will return -1. - top type, num - This takes arguments in the form:top (name) (number) Basically, - processes are ranked from highest to lowest in terms of cpu us- - age, which is what (num) represents. The types are: "name", - "pid", "cpu", and "mem". There can be a max of 10 processes - listed. + tztime (timezone (format)) + Local time for specified timezone, see man strftime to get more + information about format. The timezone argument is specified in + similar fashion as TZ environment variable. For hints, look in + /usr/share/zoneinfo. e.g. US/Pacific, Europe/Zurich, etc. - top_mem type, num - Same as top, except sorted by mem usage instead of cpu + gid_name gid + Name of group with this gid - totalup net - Total upload, this one too, may overflow + + uid_name uid + Username of user with this uid + + + unflagged_mails (maildir) (interval) + Number of mails not marked as flagged in the specified mailbox + or mail spool if not. Only maildir type mailboxes are supported, + mbox type will return -1. + + + unforwarded_mails (maildir) (interval) + Number of mails not marked as forwarded in the specified mailbox + or mail spool if not. Only maildir type mailboxes are supported, + mbox type will return -1. + + + unreplied_mails (maildir) (interval) + Number of mails not marked as replied in the specified mailbox + or mail spool if not. Only maildir type mailboxes are supported, + mbox type will return -1. + + + unseen_mails (maildir) (interval) + Number of new or unseen mails in the specified mailbox or mail + spool if not. Only maildir type mailboxes are supported, mbox + type will return -1. updates Number of updates - for debugging + for debugging - upspeed net - Upload speed in kilobytes + upspeed (net) + Upload speed in suitable IEC units - upspeedf net - Upload speed in kilobytes with one decimal + upspeedf (net) + Upload speed in KiB with one decimal - upspeedgraph net (height),(width) (gradient colour 1) (gradient colour - 2) (scale) - Upload speed graph, colours defined in hex, minus the #. If - scale is non-zero, it becomes the scale for the graph. + upspeedgraph (netdev) (height),(width) (gradient colour 1) (gradient + colour 2) (scale) (-t) (-l) + Upload speed graph, colours defined in hex, minus the #. If + scale is non-zero, it becomes the scale for the graph. Uses a + logarithmic scale (to see small numbers) when you use the -l + switch. Takes the switch '-t' to use a temperature gradient, + which makes the gradient values change depending on the ampli- + tude of a particular graph value (try it and see). uptime Uptime uptime_short - Uptime in a shorter format + Uptime in a shorter format + + + user_names + Lists the names of the users logged in + + + user_number + Number of users logged in + + + user_terms + Lists the consoles in use + + + user_times + Lists how long users have been logged in for + + + user_time console + Lists how long the user for the given console has been logged in + for + + + utime (format) + Display time in UTC (universal coordinate time). voffset (pixels) - Change vertical offset by N pixels. Negative values will cause - text to overlap. See also $offset. + Change vertical offset by N pixels. Negative values will cause + text to overlap. See also $offset. voltage_mv (n) - Returns CPU #n's voltage in mV. CPUs are counted from 1. If - omitted, the parameter defaults to 1. + Returns CPU #n's voltage in mV. CPUs are counted from 1. If + omitted, the parameter defaults to 1. voltage_v (n) - Returns CPU #n's voltage in V. CPUs are counted from 1. If omit- - ted, the parameter defaults to 1. + Returns CPU #n's voltage in V. CPUs are counted from 1. If omit- + ted, the parameter defaults to 1. - wireless_essid net - Wireless access point ESSID (Linux only) + weather URI locID data_type (interval_in_minutes) + Download, parse and display METAR data. + For the 'URI', there are two possibilities: - wireless_mode net - Wireless mode (Managed/Ad-Hoc/Master) (Linux only) + http://weather.noaa.gov/pub/data/observations/metar/stations/ + http://xoap.weather.com/weather/local/ + The first one is free to use but the second requires you to reg- + ister and obtain your partner ID and license key. These two must + be written, separated by a space, into a file called .xoaprc + which needs to be placed into your home directory. - wireless_bitrate net - Wireless bitrate (ie 11 Mb/s) (Linux only) + 'locID' must be a valid location identifier for the required + uri. For the NOAA site this must be a valid ICAO (see for in- + stance https://pilotweb.nas.faa.gov/qryhtml/icao/). For the + weather.com site this must be a valid location ID (see for in- + stance http://aspnetresources.com/tools/locid.aspx). + 'data_type' must be one of the following: - wireless_ap net - Wireless access point MAC address (Linux only) + last_update The date and time stamp of the data. The result de- + pends on the URI used. For the NOAA site it is date (yyyy/mm/dd) + and UTC time. For the weather.com one it is date ([m]m/[d]d/yy) + and Local Time of the station. + temperature + Air temperature (you can use the 'temperature_unit' config set- + ting to change units) + cloud_cover - wireless_link_qual net - Wireless link quality (Linux only) + The highest cloud cover status + pressure + Air pressure in millibar + wind_speed - wireless_link_qual_max net - Wireless link quality maximum value (Linux only) + Wind speed in km/h + wind_dir + Wind direction + wind_dir_DEG - wireless_link_qual_perc net - Wireless link quality in percents (Linux only) + Compass wind direction + humidity + Relative humidity in % + weather - wireless_link_bar (height), (width) net - Wireless link quality bar (Linux only) + Any relevant weather event (rain, snow, etc.). This is not used + if you are querying the weather.com site since this data is ag- + gregated into the cloud_cover one + icon + Weather icon (only for www.weather.com). Can be used together + with the icon kit provided upon registering to their service. - xmms2_artist - Artist in current XMMS2 song + 'delay_in_minutes' (optional, default 30) cannot be less than 30 + minutes. + This object is threaded, and once a thread is created it can't + be explicitly destroyed. One thread will run for each URI speci- + fied. - xmms2_album - Album in current XMMS2 song + Note that these variables are still EXPERIMENTAL and can be sub- + ject to many future changes. + weather_forecast URI locID day data_type (interval_in_minutes) + Download, parse and display weather forecast data for a given + day (daytime only). - xmms2_title - Title in current XMMS2 song + For the 'URI', for the time being only http://xoap.weath- + er.com/weather/local/ is supported. See 'weather' above for de- + tails of usage + 'locID', see 'weather' above. - xmms2_genre - Genre in current XMMS2 song + 'day' is a number from 0 (today) to 4 (3 days after tomorrow). + 'data_type' must be one of the following: - xmms2_comment - Comment in current XMMS2 song + day Day of the week + date Date, in the form MMM DD (ie. Jul 14) + low Minimun temperature (you can use the 'temperature_unit' con- + fig setting to change units) + hi Maximum temperature (you can use the 'temperature_unit' con- + fig setting to change units) + icon Weather icon. Can be used together with the icon kit pro- + vided upon registering to the weather.com service + forecast Weather forecast (sunny, rainy, etc.) + wind_speed Wind speed in km/h + wind_dir Wind direction + wind_dir_DEG Compass wind direction + humidity Relative humidity in % + precipitation Probability of having a precipitation (in %) + 'delay_in_minutes' (optional, default 210) cannot be lower than + 210 min. - xmms2_decoder - Decoder plugin used + This object is threaded, and once a thread is created it can't + be explicitly destroyed. One thread will run for each URI speci- + fied. You can use any protocol that Curl supports. + Note that these variables are still EXPERIMENTAL and can be sub- + ject to many future changes. - xmms2_transport - Transport plugin used + wireless_ap (net) + Wireless access point MAC address (Linux only) - xmms2_url - Full path to current song + wireless_bitrate (net) + Wireless bitrate (ie 11 Mb/s) (Linux only) - xmms2_tracknr - Track number in current XMMS2 song + wireless_essid (net) + Wireless access point ESSID (Linux only) + + + wireless_link_bar (height),(width) (net) + Wireless link quality bar (Linux only) + + + wireless_link_qual (net) + Wireless link quality (Linux only) + + + wireless_link_qual_max (net) + Wireless link quality maximum value (Linux only) + + + wireless_link_qual_perc (net) + Wireless link quality in percents (Linux only) + + + wireless_mode (net) + Wireless mode (Managed/Ad-Hoc/Master) (Linux only) + + + words textfile + Displays the number of words in the given file + + + xmms2_album + Album in current XMMS2 song + + + xmms2_artist + Artist in current XMMS2 song + + + xmms2_bar (height),(width) + Bar of XMMS2's progress xmms2_bitrate - Bitrate of current song + Bitrate of current song - xmms2_id - XMMS2 id of current song + xmms2_comment + Comment in current XMMS2 song + + + xmms2_date + Returns song's date. xmms2_duration - Duration of current song + Duration of current song xmms2_elapsed - Song's elapsed time + Song's elapsed time - xmms2_size - Size of current song + xmms2_genre + Genre in current XMMS2 song + + + xmms2_id + XMMS2 id of current song xmms2_percent - Percent of song's progress + Percent of song's progress - xmms2_status - XMMS2 status (Playing, Paused, Stopped, or Disconnected) + xmms2_playlist + Returns the XMMS2 playlist. - xmms2_bar (height),(width) - Bar of XMMS2's progress + xmms2_size + Size of current song xmms2_smart - Prints the song name in either the form "artist - title" or file - name, depending on whats available + Prints the song name in either the form "artist - title" or file + name, depending on whats available + + + xmms2_status + XMMS2 status (Playing, Paused, Stopped, or Disconnected) + + + xmms2_timesplayed + Number of times a song was played (presumably). + + + xmms2_title + Title in current XMMS2 song + xmms2_tracknr + Track number in current XMMS2 song + + + xmms2_url + Full path to current song + + +LUA API + Conky features a Lua Programming API, and also ships with Lua bindings + for some useful libraries. Conky defines certain global functions and + variables which can be accessed from Lua code running in Conky. + + To use Lua Conky, you first need to make sure you have a version of + Conky with Lua support enabled (``conky -v'' will report this). Scripts + must first be loaded using the lua_load configuration option. You then + call functions in Lua via Conky's $lua, $lua_read, and Lua hooks. + + Be careful when creating threaded objects through the Lua API. You + could wind up with a whole bunch of threads running if a thread is cre- + ated with each iteration. + + At this time, the Lua API should not be considered stable and may + change drastically from one release to another as it matures. + + NOTE: In order to accommodate certain features in the cairo library's + API, Conky will export a few additional functions for the creation of + certain structures. These are documented below. + + conky_parse(string) function + This function takes a string that is evaluated as per Conky's + TEXT section, and then returns a string with the result. + + conky_set_update_interval(number) function + Sets Conky's update interval (in seconds) to 'number'. + + conky_window table + This table contains some information about Conky's window. The + following table describes the values contained: + + drawable Window's drawable (Xlib Drawable), requires Lua extras + enabled at compile time. + visual Window's visual (Xlib Visual), requires Lua extras en- + abled at compile time. + display Window's display (Xlib Display), requires Lua extras en- + abled at compile time. + width Window width (in pixels). + height Window height (in pixels). + border_inner_margin Window's inner border margin (in pixels). + border_outer_margin Window's outer border margin (in pixels). + border_width Window's border width (in pixels). + text_start_x The x component of the starting coordinate of text + drawing. + text_start_y The y component of the starting coordinate of text + drawing. + text_width The width of the text drawing region. + text_height The height of the text drawing region. + + NOTE: This table is only defined when X support is enabled. + + conky_info table + This table contains some information about Conky's internal da- + ta. The following table describes the values contained: + + update_interval Conky's update interval (in seconds). + uptime System uptime, in seconds. + + conky_build_info string + A string containing the build info for this particular instance + of Conky, including the version, build date, and architecture. + + conky_build_date string + A string containing the build date for this particular instance + of Conky. + + conky_build_arch string + A string containing the build architecture for this particular + instance of Conky. + + conky_version string + A string containing the version of the current instance of + Conky. + + conky_config string + A string containing the path of the current Conky configuration + file. + + cairo_text_extents_t:create() function + Call this function to return a new cairo_text_extents_t struc- + ture. A creation function for this structure is not provided by + the cairo API. After calling this, you should use tolua.takeown- + ership() on the return value to ensure ownership is passed prop- + erly. + + cairo_font_extents_t:create() function + Call this function to return a new cairo_font_extents_t struc- + ture. A creation function for this structure is not provided by + the cairo API. After calling this, you should use tolua.takeown- + ership() on the return value to ensure ownership is passed prop- + erly. + + cairo_matrix_t:create() function + Call this function to return a new cairo_matrix_t structure. A + creation function for this structure is not provided by the + cairo API. After calling this, you should use tolua.takeowner- + ship() on the return value to ensure ownership is passed proper- + ly. + EXAMPLES - conky -t '${time %D %H:%m}' -o -u 30 - Start Conky in its own window with date and clock as text and 30 - sec update interval. + conky -t '${time %D %H:%M}' -o -u 30 + Start Conky in its own window with date and clock as text and 30 + sec update interval. conky -a top_left -x 5 -y 500 -d - Start Conky to background at coordinates (5, 500). + Start Conky to background at coordinates (5, 500). + + conky -C > ~/.conkyrc + Do not start Conky, but have it output the builtin default con- + fig file to ~/.conkyrc for later customising. FILES - ~/.conkyrc default configuration file + ${sysconfdir}/conky/conky.conf + Default system-wide configuration file. The value of + ${sysconfdir} depends on the compile-time options (most likely + /etc). + + ~/.conkyrc + Default personal configuration file. BUGS Drawing to root or some other desktop window directly doesn't work with all window managers. Especially doesn't work well with Gnome and it has - been reported that it doesn't work with KDE either. Nautilus can be - disabled from drawing to desktop with program gconf-editor. Uncheck - show_desktop in /apps/nautilus/preferences/. There is -w switch in - Conky to set some specific window id. You might find xwininfo -tree - useful to find the window to draw to. You can also use -o argument - which makes Conky to create its own window. + been reported that it doesn't work with KDE either. Nautilus can be + disabled from drawing to desktop with program gconf-editor. Uncheck + show_desktop in /apps/nautilus/preferences/. There is -w switch in + Conky to set some specific window id. You might find xwininfo -tree + useful to find the window to draw to. You can also use -o argument + which makes Conky to create its own window. If you do try running Conky + in its own window, be sure to read up on the own_window_type settings + and experiment. SEE ALSO - + Ÿ¨http://conky.sourceforge.net/Ÿ© - + Ÿ¨http://www.sourceforge.net/projects/conkyŸ© + + Ÿ¨http://wiki.conky.beŸ© #conky on irc.freenode.net +COPYING + Copyright (c) 2005-2010 Brenden Matthews, Philip Kovacs, et. al. Any + original torsmo code is licensed under the BSD license (see LICENSE.BSD + for a copy). All code written since the fork of torsmo is licensed un- + der the GPL (see LICENSE.GPL for a copy), except where noted different- + ly (such as in portmon code, timed thread code, and audacious code + which are LGPL, and prss which is an MIT-style license). + AUTHORS - The Conky dev team. What's up now! + The Conky dev team (see AUTHORS for a full list of contributors). - 2007-08-08 conky(1) + 2009-08-01 conky(1)