X-Git-Url: http://vcs.maemo.org/git/?a=blobdiff_plain;f=README;h=8f7c304cb18778526bc817a0d4e2ee3b75a8095f;hb=3b330910de8df9406760959a7de1e5c18a312a65;hp=69819adb394eab0bdcc4f1b8514cd463a8f94638;hpb=93d9e8c7b10efecceea6043a133092fe76a64c5b;p=monky diff --git a/README b/README index 69819ad..8f7c304 100644 --- a/README +++ b/README @@ -4,80 +4,89 @@ conky(1) conky(1) NAME conky - A system monitor for X originally based on the torsmo code, but - more kickass. It just keeps on givener. Yeah. + more kickass. It just keeps on given'er. Yeah. SYNOPSIS conky [options] DESCRIPTION - Conky is a system monitor for X originally based on the torsmo code. - Since its original conception, Conky has changed a fair bit from its + 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 its own window. Conky has many built-in objects, - as well as the ability to execute programs and scripts, then display + 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 + We are always looking for help, and anyone interested in becoming a developer is welcome. Please use the facilities at SourceForge to make bug reports, feature requests, and submit patches. Thanks for your interest in Conky. COMPILING - First, 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 Gentoos Portage. Simply use "emerge - app-admin/conky" for installation. There is also usually an up-to-date - ebuild within Conkys package or in CVS. + 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". - To compile and run Conky with all optional components: + 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 CVS. + + 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 + that some configure options may differ for your system): sh autogen.sh # Only required if building from CVS ./configure --prefix=/usr --mandir=/usr/share/man - --infodir=/usr/share/info --datadir=/usr/share --sysconfdir=/etc - --localstatedir=/var/lib --enable-double-buffer --enable-own-window - --enable-proc-uptime --enable-mpd --enable-xft --enable-seti + --infodir=/usr/share/info --datadir=/usr/share --sysconfdir=/etc + --localstatedir=/var/lib --enable-xft --enable-seti --enable-dou- + ble-buffer --enable-own-window --enable-proc-uptime --enable-mpd + --enable-mldonkey --enable-x11 --enable-portmon --enable-xmms + --enable-bmp --enable-audacious --enable-infopipe --enable-bmpx make make install # Optional - ./conky + src/conky - Conky doesnt probably compile with other compilers than gcc and icc. - It doesnt compile with C89 compiler and not even with pure C99. It - uses 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 dont + 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 dont need + You can disable 'drawing to own window' feature in case you don't need it by passing --disable-own-window to configure -script. 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 + 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 is going seriously wrong (mem leak, et - cetera). + If you do use them, please do not complain about memory or CPU usage, + unless you think something's seriously wrong (mem leak, etc.). - Easy way to force Conky to reload your ~/.conkyrc: "killall -SIGUSR1 - conky". Saves you the trouble of having to stop and then restart. + 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 - therell be a better solution in Conky 2.x... + metar stuff. mdsplib was causing way too many problems. Hopefully + there'll be a better solution in Conky 2.x... OPTIONS Command line options override configurations defined in configuration file. - -V Prints version and exits + -v | -V + Prints version and exits -a ALIGNMENT @@ -105,7 +114,7 @@ OPTIONS -t TEXT - Text to render, remember single quotes, like -t $uptime + Text to render, remember single quotes, like -t ' $uptime ' -u SECONDS @@ -125,12 +134,16 @@ OPTIONS CONFIGURATION SETTINGS - Default configuration file is $HOME/.conkyrc (can be changed from - conky.c among other things). See conkyrc.sample. You might want to copy - it to $HOME/.conkyrc and then start modifying it. + Default configuration file is $HOME/.conkyrc (can be changed from + conky.c among other things). See conkyrc.sample. If installing from + Debian package, this should be in /usr/share/doc/conky/examples ("gun- + zip conkyrc.sample.gz" to get conkyrc.sample). + + 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 + Aligned position on screen, may be top_left, top_right, bot- tom_left, bottom_right, or none @@ -160,7 +173,7 @@ CONFIGURATION SETTINGS default_shade_color - Default shading color and borders shading color + Default shading color and border's shading color default_outline_color @@ -168,8 +181,8 @@ CONFIGURATION SETTINGS double_buffer - Use the Xdbe extension? (eliminates flicker) It is highly recom - mended to use own window with this one so double buffer wont be + 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. @@ -177,6 +190,10 @@ CONFIGURATION SETTINGS Draw borders around text? + draw_graph_borders + Draw borders around graphs? + + draw_shades Draw shades? @@ -212,6 +229,16 @@ CONFIGURATION SETTINGS Minimum size of window + min_port_monitors + Allow for the creation of at least this number of port monitors + (if 0 or not set, default is 16) + + + min_port_monitor_connections + Allow each port monitor to track at least this many connections + (if 0 or not set, default is 256) + + mldonkey_hostname Hostname for mldonkey stuff, defaults to localhost @@ -258,10 +285,14 @@ CONFIGURATION SETTINGS 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 + (defaults to black). Takes either a hex value (#ffffff) or a valid RGB name (see /usr/lib/X11/rgb.txt) + out_to_console + Print text to stdout. + + pad_percents Pad percentages to this many decimals (0 = no padding) @@ -293,15 +324,21 @@ CONFIGURATION SETTINGS Use Xft (anti-aliased font and stuff) - text After this begins text to be formatted on screen + xmms_player + Use specified player/plugin for the xmms status variables. Valid + items are: none, xmms, bmp, audacious and infopipe. (default is + none). Note that bmpx is currently handled separately. + + + TEXT After this begins text to be formatted on screen VARIABLES Colors are parsed using XParsecolor(), there might be a list of them: /usr/X11R6/lib/X11/rgb.txt. Also, http://sedition.com/perl/rgb.html - 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. + [http://sedition.com/perl/rgb.html]. Color can be also in #rrggbb for- + mat (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 @@ -339,11 +376,48 @@ VARIABLES Align text to centre + apm_adapter + Display APM AC adapter status (FreeBSD only) + + + apm_battery_life + 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) + + battery (num) - Remaining capacity in ACPI or APM battery. ACPI battery number + Remaining capacity in ACPI or APM battery. ACPI battery number can be given as argument (default is BAT0). + bmpx_artist + Artist in current BMPx track + + + bmpx_album + Album in current BMPx track + + + bmpx_title + Title of the current BMPx track + + + bmpx_track + Track number of the current BMPx track + + + bmpx_bitrate + Bitrate of the current BMPx track + + + bmpx_uri + URI of the current BMPx track + + buffers Amount of memory buffered @@ -356,16 +430,17 @@ VARIABLES cpu (cpuN) - CPU usage in percents. For SMP machines, the CPU number can be + CPU usage in percents. For SMP machines, the CPU number can be provided as an argument. cpu0 is the total usage, and >=cpu1 are - individual CPUs. See $cpu for more info on SMP. + individual CPUs. cpubar (cpu number) (height),(width) - Bar that shows CPU usage, height is bars height in pixels + Bar that shows CPU usage, height is bar's height in pixels. See + $cpu for more info on SMP. - cpugraph (cpu number) (height),(width) (gradient colour 1) (gradient + 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. @@ -374,7 +449,7 @@ VARIABLES diskio Displays current disk IO. - diskiograph (height),(width) (gradient colour 1) (gradient colour 2) + 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. @@ -388,7 +463,7 @@ VARIABLES Download speed in kilobytes with one decimal - downspeedgraph net (height),(width) (gradient colour 1) (gradient + 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. @@ -398,8 +473,8 @@ VARIABLES exec command - Executes a shell command and displays the output in conky. warn - ing: this takes a lot more resources than other variables. Id + 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. @@ -414,8 +489,8 @@ VARIABLES execi interval command - Same as exec but with specific interval. Interval cant be less - than update_interval in configuration. + Same as exec but with specific interval. Interval can't be less + than update_interval in configuration. See also $texeci execibar interval command @@ -438,13 +513,13 @@ VARIABLES freq_dyn Returns CPU frequency in MHz, but is calculated by counting to - clock cycles to complete an instruction. Only available for + clock cycles to complete an instruction. Only available for x86/amd64. freq_dyn_g Returns CPU frequency in GHz, but is calculated by counting to - clock cycles to complete an instruction. Only available for + clock cycles to complete an instruction. Only available for x86/amd64. @@ -471,7 +546,7 @@ VARIABLES head logfile lines (interval) Displays first N lines of supplied text text file. If interval - is not supplied, Conky assumes 2x Conkys interval. Max of 30 + is not supplied, Conky assumes 2x Conky's interval. Max of 30 lines can be displayed, or until the text buffer is filled. @@ -480,8 +555,8 @@ VARIABLES i2c (dev), type, n - I2C sensor from sysfs (Linux 2.6). dev may be omitted if you - have only one I2C device. type is either in (or vol) meaning + I2C sensor from sysfs (Linux 2.6). dev may be omitted if you + have only one I2C device. type is either in (or vol) meaning voltage, fan meaning fan or temp/tempf (first in C, second in F) meaning temperature. n is number of the sensor. See /sys/bus/i2c/devices/ on your local computer. @@ -516,21 +591,21 @@ VARIABLES i8k_left_fan_rpm If running the i8k kernel driver for Inspiron laptops, displays - the left fans rate of rotation, in revolutions per minute as + 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 + the left fan status as listed in /proc/i8k (translated to human- + readable). Beware, some laptops i8k reports these fans in reverse order. i8k_right_fan_rpm If running the i8k kernel driver for Inspiron laptops, displays - the right fans rate of rotation, in revolutions per minute as + 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. @@ -602,46 +677,6 @@ VARIABLES Percentage of memory in use - ml_upload_counter - total session upload in mb - - - ml_download_counter - total session download in mb - - - ml_nshared_files - number of shared files - - - ml_shared_counter - total session shared in mb, buggy in some mldonkey versions - - - ml_tcp_upload_rate - tcp upload rate in kb/s - - - ml_tcp_download_rate - tcp download rate in kb/s - - - ml_udp_upload_rate - udp upload rate in kb/s - - - ml_udp_download_rate - udp download rate in kb/s - - - ml_ndownloaded_files - number of completed files - - - ml_ndownloading_files - number of downloading files - - mpd_artist Artist in current MPD song must be enabled at compile @@ -651,7 +686,7 @@ VARIABLES mpd_bar (height),(width) - Bar of mpds progress + Bar of mpd's progress mpd_bitrate @@ -667,19 +702,31 @@ VARIABLES mpd_vol - MPDs volume + MPD's volume mpd_elapsed - Songs elapsed time + Song's elapsed time mpd_length - Songs length + Song's length mpd_percent - Percent of songs progress + Percent of song's progress + + + mpd_random + Random status (On/Off) + + + mpd_repeat + Repeat status (On/Off) + + + mpd_track + Prints the MPD track field new_mails @@ -734,32 +781,92 @@ VARIABLES 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 + + lip - local ip address + + lhost - local host name + + 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 + index 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 + interval at least 6 seconds. See also $execi. + + offset (pixels) Move text over by N pixels. See also $voffset. tail logfile lines (interval) Displays last N lines of supplied text text file. If interval is - not supplied, Conky assumes 2x Conkys interval. Max of 30 lines + not supplied, Conky assumes 2x Conky's interval. Max of 30 lines can be displayed, or until the text buffer is filled. time (format) - Local time, see man strftime to get more information about for + Local time, see man strftime to get more information about for- mat totaldown net - Total download, overflows at 4 GB on Linux with 32-bit arch and - there doesnt seem to be a way to know how many times it has + 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 already done that before conky has started. top type, num - This takes arguments in the form:top (name) (number) Basically, - processes are ranked from highest to lowest in terms of cpu - usage, which is what (num) represents. The types are: "name", - "pid", "cpu", and mem". There can be a max of 10 processes + This takes arguments in the form:top (name) (number) Basically, + processes are ranked from highest to lowest in terms of cpu + usage, which is what (num) represents. The types are: "name", + "pid", "cpu", and mem". There can be a max of 10 processes listed. @@ -783,9 +890,9 @@ VARIABLES Upload speed in kilobytes with one decimal - upspeedgraph net (height),(width) (gradient colour 1) (gradient colour + upspeedgraph net (height),(width) (gradient colour 1) (gradient colour 2) (scale) - Upload speed graph, colours defined in hex, minus the #. If + Upload speed graph, colours defined in hex, minus the #. If scale is non-zero, it becomes the scale for the graph. @@ -809,12 +916,73 @@ VARIABLES voffset (pixels) - Change verticle offset by N pixels. Negative values will cause + Change verticle offset by N pixels. Negative values will cause text to overlap. See also $offset. + xmms_bar (height),(width) + xmms / bmp / audacious / infopipe: progress bar + + + xmms_bitrate + xmms / bmp / audacious / infopipe: bitrate of current tune + + + xmms_channels + xmms / bmp / audacious / infopipe: number of audio channels of + current tune + + + xmms_filename + xmms / bmp / audacious / infopipe: full path and filename of + current tune + + + xmms_frequency + xmms / bmp / audacious / infopipe: sampling frequency of current + tune + + + xmms_length + xmms / bmp / audacious / infopipe: total length of current tune + as MM:SS + + + xmms_length_seconds + xmms / bmp / audacious / infopipe: total length of current tune + in seconds + + + xmms_playlist_position + xmms / bmp / audacious / infopipe: playlist position of current + tune + + + xmms_playlist_length + xmms / bmp / audacious / infopipe: number of tunes in playlist + + + xmms_position + xmms / bmp / audacious / infopipe: MM:SS position of current + tune + + + xmms_position_seconds + xmms / bmp / audacious / infopipe: position of current tune in + seconds + + + xmms_status + xmms / bmp / audacious / infopipe: player status (Play- + ing/Paused/Stopped/Not running) + + + xmms_title + xmms / bmp / audacious / infopipe: title of current tune + + EXAMPLES - conky -t${time %D %H:%m}-o -u 30 + 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. @@ -825,25 +993,26 @@ FILES ~/.conkyrc default configuration file BUGS - Drawing to root or some other desktop window directly doesnt work with - all window managers. Especially doesnt work well with Gnome and it has - been reported that it doesnt 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 + 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. SEE ALSO - http://conky.sourceforge.net + http://conky.sourceforge.net [http://conky.sourceforge.net] - http://www.sourceforge.net/projects/conky + http://www.sourceforge.net/projects/conky [http://www.source- + forge.net/projects/conky] #conky on irc.freenode.net AUTHORS - The Conky dev team. Whats up now! + The Conky dev team. What's up now! - 2005-08-27 conky(1) + 2006-01-01 conky(1)