forked from brndnmtthws/conky
-
Notifications
You must be signed in to change notification settings - Fork 0
Manpage
Georgi Valkov edited this page Dec 26, 2012
·
1 revision
conky(1) conky(1)
NAME
conky - A system monitor for X originally based on the torsmo code, but more
kickass. It just keeps on given'er. Yeah.
SYNOPSIS
conky [ options ]
DESCRIPTION
Conky is a system monitor for X originally based on torsmo. Since its inception,
Conky has changed significantly from its predecessor, while maintaining simplici‐
ty 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 ob‐
jects, it can also display just about any piece of information by using scripts
and other external programs.
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, fea‐
ture 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 on a binary distro, make sure you have the X de‐
velopment 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 reading errors that you get from './configure'. You can enable/dis‐
able stuff by giving options to configure, but be careful with disabling. For ex‐
ample: 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 dis‐
tributions. Here are some installation instructions for a few:
Gentoo users -- Conky is in Gentoo's Portage... simply use "emerge app-ad‐
min/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 the git repo
./configure --prefix=/usr --mandir=/usr/share/man --infodir=/usr/share/info
--datadir=/usr/share --sysconfdir=/etc --localstatedir=/var/lib --dis‐
able-own-window --enable-audacious[=yes|no|legacy] --enable-bmpx --disable-hd‐
dtemp --disable-mpd --enable-xmms2 --disable-portmon --disable-network --en‐
able-debug --disable-x11 --disable-double-buffer --disable-xdamage --disable-xft
make
make install # Optional
src/conky
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. 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. You can now also do the
same with SIGHUP.
OPTIONS
Command line options override configurations defined in configuration file.
-v | -V | --version
Prints version and exits
-q | --quiet
Run Conky in 'quiet mode' (ie. no output)
-D | --debug
Increase debugging output, ie. -DD for more debugging
-a | --alignment= ALIGNMENT
Text alignment on screen, {top,bottom,middle}_{left,right,middle} or none.
Can also be abbreviated with first chars of position, ie. tr for
top_right.
-b | --double-buffer
Use double buffering (eliminates "flicker")
-c | --config= FILE
Config file to load instead of $HOME/.conkyrc
-C | --print-config
Print builtin default config to stdout. See also the section EXAMPLES for
more information.
-d | --daemonize
Daemonize Conky, aka fork to background
-f | --font= FONT
Font to use
-h | --help
Prints command line help and exits
-o | --own-window
Create own window to draw
-t | --text= TEXT
Text to render, remember single quotes, like -t ' $uptime '
-p | --pause= SECONDS
Time to pause before actually starting Conky
-u | --interval= SECONDS
Update interval
-w | --window-id= WIN_ID
Window id to draw
-X | --display= DISPLAY
X11 display to use
-x X_COORDINATE
X position
-y Y_COORDINATE
Y position
-i COUNT
Number of times to update Conky (and quit)
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/
...
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 de‐
stroyed 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 pa‐
rameters as a 'key', so that you only have 1 relevant thread running (for exam‐
ple, the $curl, $rss and $weather objects launch one thread per URI).
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 created with each iteration.
At this time, the Lua API should not be considered stable and may change drasti‐
cally 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 sec‐
tion, 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 enabled at com‐
pile time.
display Window's display (Xlib Display), requires Lua extras enabled 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 data. The fol‐
lowing 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 structure. A cre‐
ation function for this structure is not provided by the cairo API. After
calling this, you should use tolua.takeownership() on the return value to
ensure ownership is passed properly.
cairo_font_extents_t:create() function
Call this function to return a new cairo_font_extents_t structure. A cre‐
ation function for this structure is not provided by the cairo API. After
calling this, you should use tolua.takeownership() on the return value to
ensure ownership is passed properly.
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 call‐
ing this, you should use tolua.takeownership() on the return value to en‐
sure ownership is passed properly.
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 up‐
date 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 config file to
~/.conkyrc for later customising.
FILES
${sysconfdir}/conky/conky.conf
Default system-wide configuration file. The value of ${sysconfdir} de‐
pends 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 win‐
dow 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/prefer‐
ences/. 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 experi‐
ment.
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 under the GPL (see LICENSE.GPL
for a copy), except where noted differently (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 (see AUTHORS for a full list of contributors).
2012-05-03 conky(1)