+ ibm_volume
+ If running the IBM ACPI, displays the "master" volume, con-
+ trolled by the volume keys (0-14).
+
+
+ iconv_start codeset_from codeset_to
+ Convert text from one codeset to another using GNU iconv. Needs
+ to be stopped with iconv_stop.
+
+
+ iconv_stop
+ Stop iconv codeset conversion.
+
+
+ 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_gw if there is at least one default gateway, display everything be-
+ tween $if_gw and the matching $endif
+
+
+ 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 (")
+
+ Valid operands are: '>', '<', '>=', '<=', '==', '!='.
+
+
+ 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.
+
+
+ if_mounted (mountpoint)
+ if MOUNTPOINT is mounted, display everything between $if_mounted
+ and the matching $endif
+
+
+ if_mpd_playing
+ if mpd is playing or paused, display everything between
+ $if_mpd_playing and the matching $endif
+
+
+ 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.
+
+
+ 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
+
+
+ if_up (interface)
+ if INTERFACE exists and is up, display everything between $if_up
+ and the matching $endif
+
+
+ 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.
+
+
+ if_xmms2_connected
+ Display everything between $if_xmms2_connected and the matching
+ $endif if xmms2 is running.
+
+
+ image <path to 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.
+
+
+ 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.
+
+
+ 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.
+
+
+ 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")
+
+
+ kernel Kernel version
+
+
+ laptop_mode
+ The value of /proc/sys/vm/laptop_mode
+
+
+ lines textfile
+ Displays the number of lines in the given file
+
+
+ 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.
+
+
+ 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).
+
+
+ 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.
+
+
+ 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.
+
+
+ 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.
+
+
+ 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.
+
+
+ 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.
+
+
+ machine
+ Machine, i686 for example
+
+
+ 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.
+
+
+ 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"}
+
+
+ mem Amount of memory in use
+
+
+ membar (height),(width)
+ Bar that shows amount of memory in use
+
+
+ memeasyfree
+ Amount of free memory including the memory that is very easily
+ freed (buffers/cache)
+
+
+ memfree
+ Amount of free memory
+
+
+ memgauge (height),(width)
+ Gauge that shows amount of memory in use (see cpugauge)
+
+
+ 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).
+
+
+ memmax Total amount of memory
+
+
+ memperc
+ Percentage of memory in use
+
+
+ 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.
+
+
+ mixerbar (device)
+ Displays mixer value in a bar as reported by the OS. See docs
+ for $mixer for details on arguments.
+
+
+ mixerl (device)
+ Prints the left channel mixer value as reported by the OS. See
+ docs for $mixer for details on arguments.
+
+
+ mixerlbar (device)
+ Displays the left channel mixer value in a bar as reported by
+ the OS. See docs for $mixer for details on arguments.
+
+
+ mixerr (device)
+ Prints the right channel mixer value as reported by the OS. See
+ docs for $mixer for details on arguments.
+
+
+ mixerrbar (device)
+ Displays the right channel mixer value in a bar as reported by
+ the OS. See docs for $mixer for details on arguments.
+
+
+ moc_album
+ Album of the current MOC song
+
+
+ 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.
+
+
+ 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
+
+
+ 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'.
+ 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
+ \94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94\94
+ ${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.
+
+
+ threads
+ Total threads
+
+
+ time (format)
+ Local time, see man strftime to get more information about for-
+ mat
+
+
+ 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.
+
+
+ totalup (net)
+ Total upload, this one too, may overflow
+
+
+ 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.
+
+
+ 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.
+
+
+ gid_name gid
+ Name of group with this gid
+
+
+ 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
+
+
+ upspeed (net)
+ Upload speed in suitable IEC units
+
+
+ upspeedf (net)
+ Upload speed in KiB with one decimal
+
+
+ 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
+
+
+ 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.
+
+
+ voltage_mv (n)
+ 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.
+
+
+ weather URI locID data_type (interval_in_minutes)
+ Download, parse and display METAR data.
+
+ For the 'URI', there are two possibilities:
+
+ 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.
+
+ '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:
+
+ 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
+
+ The highest cloud cover status
+ pressure
+
+ Air pressure in millibar
+ wind_speed
+
+ Wind speed in km/h
+ wind_dir
+
+ Wind direction
+ wind_dir_DEG
+
+ Compass wind direction
+ humidity
+
+ Relative humidity in %
+ weather
+
+ 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.
+
+ '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.
+
+ 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).
+
+ 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.
+
+ 'day' is a number from 0 (today) to 4 (3 days after tomorrow).
+
+ 'data_type' must be one of the following:
+
+ 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.
+
+ 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.
+
+ wireless_ap (net)
+ Wireless access point MAC address (Linux only)
+
+
+ wireless_bitrate (net)
+ Wireless bitrate (ie 11 Mb/s) (Linux only)
+
+
+ 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
+
+
+ xmms2_comment
+ Comment in current XMMS2 song
+
+
+ xmms2_date
+ Returns song's date.
+
+
+ xmms2_duration
+ Duration of current song
+
+
+ xmms2_elapsed
+ Song's elapsed time
+
+
+ xmms2_genre
+ Genre in current XMMS2 song
+
+
+ xmms2_id
+ XMMS2 id of current song
+
+
+ xmms2_percent
+ Percent of song's progress
+
+
+ xmms2_playlist
+ Returns the XMMS2 playlist.
+
+
+ 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
+
+
+ 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 -a top_left -x 5 -y 500 -d
+ 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
+ ${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. 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
+ \9f¨http://conky.sourceforge.net/\9f©
+
+ \9f¨http://www.sourceforge.net/projects/conky\9f©
+
+ \9f¨http://wiki.conky.be\9f©