vcs.maemo.org Git - monky/blob - README

   1 conky(1)                                                              conky(1)
   2
   3
   4
   5 NAME
   6        conky - A system monitor for X originally based on the torsmo code, but
   7        more kickass. It just keeps on given'er. Yeah.
   8
   9 SYNOPSIS
  10        conky [options]
  11
  12 DESCRIPTION
  13        Conky is a system monitor for X originally based on  the  torsmo  code.
  14        Since  it's original conception, Conky has changed a fair bit from it's
  15        predecessor.  Conky can display just about  anything,  either  on  your
  16        root  desktop  or in it's own window.  Conky has many built-in objects,
  17        as well as the ability to execute programs and  scripts,  then  display
  18        the output from stdout.
  19
  20        We  are  always  looking  for help, and anyone interested in becoming a
  21        developer is welcome.  Please use the facilities at SourceForge to make
  22        bug reports, feature requests, and submit patches.
  23
  24        Thanks for your interest in Conky.
  25
  26 COMPILING
  27        For  users  compiling from source, make sure you have the X development
  28        libraries installed.  This should be  a  package  along  the  lines  of
  29        "libx11-dev or xorg-x11-dev".
  30
  31        Gentoo users -- Conky is in Gentoo's Portage... simply use "emerge app-
  32        admin/conky" for installation.  There is  also  usually  an  up-to-date
  33        ebuild within Conky's package or in CVS.
  34
  35        Debian,etc.  users  --  Conky will be in Debian's repositories soon (by
  36        mid-September, hopefully), and then Ubuntu  shortly  thereafter.  Until
  37        then, "dpkg -i" the .deb package to install.
  38
  39        To compile and run Conky with all optional components:
  40
  41        sh autogen.sh # Only required if building from CVS
  42
  43        ./configure            --prefix=/usr            --mandir=/usr/share/man
  44        --infodir=/usr/share/info    --datadir=/usr/share     --sysconfdir=/etc
  45        --localstatedir=/var/lib   --enable-double-buffer   --enable-own-window
  46        --enable-proc-uptime --enable-mpd --enable-xft --enable-seti
  47
  48        make
  49
  50        make install # Optional
  51
  52        src/conky
  53
  54        Conky  probably  doesn't compile with compilers other than gcc and icc.
  55        It doesn't compile with C89 compiler and not even with  pure  C99.   It
  56        uses  a  few things that might not exist: strdup(), strcasecmp(), strn-
  57        casecmp(), optarg variable with getopt() and long long  (not  in  C89).
  58        Crashes in file system statistics stuff when compiled with icc, I don't
  59        know exactly why.
  60
  61        You can disable 'drawing to own window' feature in case you don't  need
  62        it by passing --disable-own-window to configure -script.
  63
  64
  65 YOU SHOULD KNOW
  66        Conky  is generally very good on resources. However, certain objects in
  67        Conky are harder on resources then others. In  particular,  the  $tail,
  68        $top,  $font,  and $graph objects are quite costly in comparison to the
  69        rest of Conky.
  70
  71        If you do use them, please do not complain about memory or  CPU  usage,
  72        unless you think something's seriously wrong (mem leak, etc.).
  73
  74        An easy way to force Conky to reload your ~/.conkyrc: "killall -SIGUSR1
  75        conky".  Saves you the trouble of having to kill and then restart.
  76
  77        IMPORTANT: For previous Conky users, Conky 1.3 no longer  supports  the
  78        metar  stuff.   mdsplib  was  causing  way too many problems. Hopefully
  79        there'll be a better solution in Conky 2.x...
  80
  81 OPTIONS
  82        Command line options override configurations defined  in  configuration
  83        file.
  84
  85        -v | -V
  86               Prints version and exits
  87
  88
  89        -a ALIGNMENT
  90               Text alignment on screen, {top,bottom}_{left,right} or none
  91
  92
  93        -b     Use double buffering (eliminates "flicker")
  94
  95
  96        -c FILE
  97               Config file to load instead of $HOME/.conkyrc
  98
  99
 100        -d     Daemonize Conky, aka fork to background
 101
 102
 103        -f FONT
 104               Font to use
 105
 106
 107        -h     Prints command line help and exits
 108
 109
 110        -o     Create own window to draw
 111
 112
 113        -t TEXT
 114               Text to render, remember single quotes, like -t ' $uptime '
 115
 116
 117        -u SECONDS
 118               Update interval
 119
 120
 121        -w WIN_ID
 122               Window id to draw
 123
 124
 125        -x X_COORDINATE
 126               X position
 127
 128
 129        -y Y_COORDINATE
 130               Y position
 131
 132
 133 CONFIGURATION SETTINGS
 134        Default  configuration  file  is  $HOME/.conkyrc  (can  be changed from
 135        conky.c among other things). See  conkyrc.sample.  If  installing  from
 136        Debian  package, this should be in /usr/share/doc/conky/examples ("gun-
 137        zip conkyrc.sample.gz" to get conkyrc.sample).
 138
 139        You might want to copy it to $HOME/.conkyrc and  then  start  modifying
 140        it.  Other configs can be found at http://conky.sf.net
 141
 142        alignment
 143               Aligned  position  on  screen,  may be top_left, top_right, bot-
 144               tom_left, bottom_right, or none
 145
 146
 147        background
 148               Boolean value, if true, Conky will be forked to background  when
 149               started
 150
 151
 152        on_bottom
 153               Set conky on the bottom of all other applications
 154
 155
 156        border_margin
 157               Border margin in pixels
 158
 159
 160        border_width
 161               Border width in pixels
 162
 163
 164        cpu_avg_samples
 165               The number of samples to average for CPU monitoring
 166
 167
 168        default_color
 169               Default color and border color
 170
 171
 172        default_shade_color
 173               Default shading color and border's shading color
 174
 175
 176        default_outline_color
 177               Default outline color
 178
 179
 180        double_buffer
 181               Use the Xdbe extension? (eliminates flicker) It is highly recom-
 182               mended to use own window with this one so double buffer won't be
 183               so big.
 184
 185
 186        draw_borders
 187               Draw borders around text?
 188
 189
 190        draw_shades
 191               Draw shades?
 192
 193
 194        draw_outline
 195               Draw outlines?
 196
 197
 198        font   Font name in X, xfontsel can be used to get a nice font
 199
 200
 201        gap_x  Gap  between  right or left border of screen, same as passing -x
 202               at command line
 203
 204
 205        gap_y  Gap between top or bottom border of screen, same as  passing  -y
 206               at command line
 207
 208
 209        no_buffers
 210               Substract (file system) buffers from used memory?
 211
 212
 213        mail_spool
 214               Mail spool for mail checking
 215
 216
 217        maximum_width pixels
 218               Maximum width of window
 219
 220
 221        minimum_size width (height)
 222               Minimum size of window
 223
 224
 225        mldonkey_hostname
 226               Hostname for mldonkey stuff, defaults to localhost
 227
 228
 229        mldonkey_port
 230               Mldonkey port, 4001 default
 231
 232
 233        mldonkey_login
 234               Mldonkey login, default none
 235
 236
 237        mldonkey_password
 238               Mldonkey password, default none
 239
 240
 241        mpd_host
 242               Host of MPD server
 243
 244
 245        mpd_port
 246               Port of MPD server
 247
 248
 249        mpd_password
 250               MPD server password
 251
 252
 253        net_avg_samples
 254               The number of samples to average for net data
 255
 256
 257        override_utf8_locale
 258               Force UTF8? requires XFT
 259
 260
 261        own_window
 262               Boolean, create own window to draw?
 263
 264
 265        own_window_transparent
 266               Boolean, set pseudo-transparency?
 267
 268
 269        own_window_colour colour
 270               If  own_window_transparent no, set a specified background colour
 271               (defaults to black). Takes either a hex  value  (#ffffff)  or  a
 272               valid RGB name (see /usr/lib/X11/rgb.txt)
 273
 274
 275        pad_percents
 276               Pad percentages to this many decimals (0 = no padding)
 277
 278
 279        stippled_borders
 280               Border stippling (dashing) in pixels
 281
 282
 283        total_run_times
 284               Total  number of times for Conky to update before quitting. Zero
 285               makes Conky run forever
 286
 287
 288        update_interval
 289               Update interval in seconds
 290
 291
 292        uppercase
 293               Boolean value, if true, text is rendered in upper case
 294
 295
 296        use_spacer
 297               Adds spaces after certain objects to stop them from moving other
 298               things around. Note that this only helps if you are using a mono
 299               font, such as Bitstream Vera Sans Mono.
 300
 301
 302        use_xft
 303               Use Xft (anti-aliased font and stuff)
 304
 305
 306        TEXT   After this begins text to be formatted on screen
 307
 308
 309 VARIABLES
 310        Colors are parsed using XParsecolor(), there might be a list  of  them:
 311        /usr/X11R6/lib/X11/rgb.txt.   Also,   http://sedition.com/perl/rgb.html
 312        [http://sedition.com/perl/rgb.html].  Color can be also in #rrggbb for-
 313        mat (hex).  Note that when displaying bytes, power is 1024 and not 1000
 314        so 1M really means 1024*1024 bytes and not 1000*1000.
 315
 316        addr interface
 317               IP address for an interface
 318
 319
 320        acpiacadapter
 321               ACPI ac adapter state.
 322
 323
 324        acpifan
 325               ACPI fan state
 326
 327
 328        acpitemp
 329               ACPI temperature in C.
 330
 331
 332        acpitempf
 333               ACPI temperature in F.
 334
 335
 336        adt746xcpu
 337               CPU temperature from therm_adt746x
 338
 339
 340        adt746xfan
 341               Fan speed from therm_adt746x
 342
 343
 344        alignr (num)
 345               Right-justify text, with space of N
 346
 347
 348        alignc (num)
 349               Align text to centre
 350
 351
 352        apm_adapter
 353               Display APM AC adapter status (FreeBSD only)
 354
 355
 356        apm_battery_life
 357               Display APM battery life in percent (FreeBSD only)
 358
 359
 360        apm_battery_time
 361               Display remaining APM battery life in hh:mm:ss or  "unknown"  if
 362               AC adapterstatus is on-line or charging (FreeBSD only)
 363
 364
 365        battery (num)
 366               Remaining  capacity  in ACPI or APM battery. ACPI battery number
 367               can be given as argument (default is BAT0).
 368
 369
 370        buffers
 371               Amount of memory buffered
 372
 373
 374        cached Amount of memory cached
 375
 376
 377        color (color)
 378               Change drawing color to color
 379
 380
 381        cpu (cpuN)
 382               CPU usage in percents. For SMP machines, the CPU number  can  be
 383               provided as an argument. cpu0 is the total usage, and >=cpu1 are
 384               individual CPUs.
 385
 386
 387        cpubar (cpu number) (height),(width)
 388               Bar that shows CPU usage, height is bar's height in pixels.  See
 389               $cpu for more info on SMP.
 390
 391
 392        cpugraph  (cpu  number)  (height),(width) (gradient colour 1) (gradient
 393        colour 2)
 394               CPU  usage graph, with optional colours in hex, minus the #. See
 395               $cpu for more info on SMP.
 396
 397
 398        diskio Displays current disk IO.
 399
 400
 401        diskiograph (height),(width) (gradient colour 1)  (gradient  colour  2)
 402        (scale)
 403               Disk IO graph, colours defined in hex, minus the #. If scale  is
 404               non-zero, it becomes the scale for the graph.
 405
 406
 407        downspeed net
 408               Download speed in kilobytes
 409
 410
 411        downspeedf net
 412               Download speed in kilobytes with one decimal
 413
 414
 415        downspeedgraph  net  (height),(width)  (gradient  colour  1)  (gradient
 416        colour 2) (scale)
 417               Download  speed  graph,  colours defined in hex, minus the #. If
 418               scale is non-zero, it becomes the scale for the graph.
 419
 420
 421        else   Text to show if any of the above are not true
 422
 423
 424        exec command
 425               Executes a shell command and displays the output in conky. warn-
 426               ing:  this  takes a lot more resources than other variables. I'd
 427               recommend coding wanted behaviour in C and posting a patch.
 428
 429
 430        execbar command
 431               Same as exec, except if  the  first  value  return  is  a  value
 432               between  0-100,  it will use that number for a bar. The size for
 433               the bar is currently fixed, but that may change in the future.
 434
 435
 436        execgraph command
 437               Same as execbar, but graphs values.
 438
 439
 440        execi interval command
 441               Same as exec but with specific interval. Interval can't be  less
 442               than update_interval in configuration. See also $texeci
 443
 444
 445        execibar interval command
 446               Same as execbar, except with an interval
 447
 448
 449        execigraph interval command
 450               Same as execigraph, but takes an interval arg graphs values
 451
 452
 453        font font
 454               Specify a different font. Only applies to one line.
 455
 456
 457        freq   Returns CPU frequency in MHz
 458
 459
 460        freq_g Returns CPU frequency in GHz
 461
 462
 463        freq_dyn
 464               Returns  CPU  frequency in MHz, but is calculated by counting to
 465               clock cycles to complete  an  instruction.  Only  available  for
 466               x86/amd64.
 467
 468
 469        freq_dyn_g
 470               Returns  CPU  frequency in GHz, but is calculated by counting to
 471               clock cycles to complete  an  instruction.  Only  available  for
 472               x86/amd64.
 473
 474
 475        fs_bar (height),(width) fs
 476               Bar  that  shows how much space is used on a file system. height
 477               is the height in pixels. fs is any file on that file system.
 478
 479
 480        fs_free (fs)
 481               Free space on a file system available for users.
 482
 483
 484        fs_free_perc (fs)
 485               Free percentage of space on a file system available for users.
 486
 487
 488        fs_size (fs)
 489               File system size
 490
 491
 492        fs_used (fs)
 493               File system used space
 494
 495
 496        head logfile lines (interval)
 497               Displays first N lines of supplied text text file.  If  interval
 498               is  not  supplied,  Conky assumes 2x Conky's interval. Max of 30
 499               lines can be displayed, or until the text buffer is filled.
 500
 501
 502        hr (height)
 503               Horizontal line, height is the height in pixels
 504
 505
 506        i2c (dev), type, n
 507               I2C sensor from sysfs (Linux 2.6). dev may  be  omitted  if  you
 508               have  only  one  I2C  device. type is either in (or vol) meaning
 509               voltage, fan meaning fan or temp/tempf (first in C, second in F)
 510               meaning   temperature.   n   is   number   of  the  sensor.  See
 511               /sys/bus/i2c/devices/ on your local computer.
 512
 513
 514        i8k_ac_status
 515               If running the i8k kernel driver for Inspiron laptops,  displays
 516               whether  ac  power  is on, as listed in /proc/i8k (translated to
 517               human-readable). Beware that this is by default not  enabled  by
 518               i8k itself.
 519
 520
 521        i8k_bios
 522               If  running the i8k kernel driver for Inspiron laptops, displays
 523               the bios version as listed in /proc/i8k.
 524
 525
 526        i8k_buttons_status
 527               If running the i8k kernel driver for Inspiron laptops,  displays
 528               the volume buttons status as listed in /proc/i8k.
 529
 530
 531        i8k_cpu_temp
 532               If  running the i8k kernel driver for Inspiron laptops, displays
 533               the cpu temperature in celsius, as reported by /proc/i8k.
 534
 535
 536        i8k_cpu_tempf
 537               If running the i8k kernel driver for Inspiron laptops,  displays
 538               the cpu temperature in farenheit, as reported by /proc/i8k.
 539
 540
 541        i8k_left_fan_rpm
 542               If  running the i8k kernel driver for Inspiron laptops, displays
 543               the left fan's rate of rotation, in revolutions  per  minute  as
 544               listed in /proc/i8k. Beware, some laptops i8k reports these fans
 545               in reverse order.
 546
 547
 548        i8k_left_fan_status
 549               If running the i8k kernel driver for Inspiron laptops,  displays
 550               the left fan status as listed in /proc/i8k (translated to human-
 551               readable). Beware,  some  laptops  i8k  reports  these  fans  in
 552               reverse order.
 553
 554
 555        i8k_right_fan_rpm
 556               If  running the i8k kernel driver for Inspiron laptops, displays
 557               the right fan's rate of rotation, in revolutions per  minute  as
 558               listed in /proc/i8k. Beware, some laptops i8k reports these fans
 559               in reverse order.
 560
 561
 562        i8k_right_fan_status
 563               If running the i8k kernel driver for Inspiron laptops,  displays
 564               the  right  fan  status  as  listed  in /proc/i8k (translated to
 565               human-readable). Beware, some laptops i8k reports these fans  in
 566               reverse order.
 567
 568
 569        i8k_serial
 570               If  running the i8k kernel driver for Inspiron laptops, displays
 571               your laptop serial number as listed in /proc/i8k.
 572
 573
 574        i8k_version
 575               If running the i8k kernel driver for Inspiron laptops,  displays
 576               the version formatting of /proc/i8k.
 577
 578
 579        if_running (process)
 580               if  PROCESS  is  running,  display everything if_running and the
 581               matching $endif
 582
 583
 584        if_existing (file)
 585               if FILE exists, display everything between if_existing  and  the
 586               matching $endif
 587
 588
 589        if_mounted (mountpoint)
 590               if  MOUNTPOINT is mounted, display everything between if_mounted
 591               and the matching $endif
 592
 593
 594        kernel Kernel version
 595
 596
 597        linkstatus interface
 598               Get the link status for wireless connections
 599
 600
 601        loadavg
 602               (1,2,3)> System load average, 1 is for past 1 minute, 2 for past
 603               5 minutes and 3 for past 15 minutes.
 604
 605
 606        machine
 607               Machine, i686 for example
 608
 609
 610        mails  Mail  count in mail spool. You can use program like fetchmail to
 611               get mails from some server using your  favourite  protocol.  See
 612               also new_mails.
 613
 614
 615        mem    Amount of memory in use
 616
 617
 618        membar (height),(width)
 619               Bar that shows amount of memory in use
 620
 621
 622        memmax Total amount of memory
 623
 624
 625        memperc
 626               Percentage of memory in use
 627
 628
 629        ml_upload_counter
 630               total session upload in mb
 631
 632
 633        ml_download_counter
 634               total session download in mb
 635
 636
 637        ml_nshared_files
 638               number of shared files
 639
 640
 641        ml_shared_counter
 642               total session shared in mb, buggy in some mldonkey versions
 643
 644
 645        ml_tcp_upload_rate
 646               tcp upload rate in kb/s
 647
 648
 649        ml_tcp_download_rate
 650               tcp download rate in kb/s
 651
 652
 653        ml_udp_upload_rate
 654               udp upload rate in kb/s
 655
 656
 657        ml_udp_download_rate
 658               udp download rate in kb/s
 659
 660
 661        ml_ndownloaded_files
 662               number of completed files
 663
 664
 665        ml_ndownloading_files
 666               number of downloading files
 667
 668
 669        mpd_artist
 670               Artist in current MPD song must be enabled at compile
 671
 672
 673        mpd_album
 674               Album in current MPD song
 675
 676
 677        mpd_bar (height),(width)
 678               Bar of mpd's progress
 679
 680
 681        mpd_bitrate
 682               Bitrate of current song
 683
 684
 685        mpd_status
 686               Playing, stopped, et cetera.
 687
 688
 689        mpd_title
 690               Title of current MPD song
 691
 692
 693        mpd_vol
 694               MPD's volume
 695
 696
 697        mpd_elapsed
 698               Song's elapsed time
 699
 700
 701        mpd_length
 702               Song's length
 703
 704
 705        mpd_percent
 706               Percent of song's progress
 707
 708
 709        mpd_random
 710               Random status (On/Off)
 711
 712
 713        mpd_repeat
 714               Repeat status (On/Off)
 715
 716
 717        mpd_track
 718               Prints the MPD track field
 719
 720
 721        new_mails
 722               Unread mail count in mail spool.
 723
 724
 725        nodename
 726               Hostname
 727
 728
 729        outlinecolor (color)
 730               Change outline color
 731
 732
 733        pre_exec shell command
 734               Executes a shell command one time before conky displays anything
 735               and puts output as text.
 736
 737
 738        processes
 739               Total processes (sleeping and running)
 740
 741
 742        running_processes
 743               Running processes (not sleeping), requires Linux 2.6
 744
 745
 746        shadecolor (color)
 747               Change shading color
 748
 749
 750        stippled_hr (space)
 751               Stippled (dashed) horizontal line
 752
 753
 754        swapbar (height),(width)
 755               Bar that shows amount of swap in use
 756
 757
 758        swap   Amount of swap in use
 759
 760
 761        swapmax
 762               Total amount of swap
 763
 764
 765        swapperc
 766               Percentage of swap in use
 767
 768
 769        sysname
 770               System name, Linux for example
 771
 772
 773        texeci interval command
 774               Runs a command at an interval inside a thread and  displays  the
 775               output.  Same  as  $execi,  except  the  command is run inside a
 776               thread. Use this if you have a slow script to keep Conky  updat-
 777               ing.  You should make the interval slightly longer then the time
 778               it takes your script to execute. For  example,  if  you  have  a
 779               script  that  take  5  seconds  to  execute, you should make the
 780               interval at least 6 seconds. See also $execi.
 781
 782
 783        offset (pixels)
 784               Move text over by N pixels. See also $voffset.
 785
 786
 787        tail logfile lines (interval)
 788               Displays last N lines of supplied text text file. If interval is
 789               not supplied, Conky assumes 2x Conky's interval. Max of 30 lines
 790               can be displayed, or until the text buffer is filled.
 791
 792
 793        time (format)
 794               Local time, see man strftime to get more information about  for-
 795               mat
 796
 797
 798        totaldown net
 799               Total  download, overflows at 4 GB on Linux with 32-bit arch and
 800               there doesn't seem to be a way to know how  many  times  it  has
 801               already done that before conky has started.
 802
 803
 804        top type, num
 805               This  takes arguments in the form:top (name) (number) Basically,
 806               processes are ranked from highest to  lowest  in  terms  of  cpu
 807               usage,  which  is  what (num) represents. The types are: "name",
 808               "pid", "cpu", and mem". There can  be  a  max  of  10  processes
 809               listed.
 810
 811
 812        top_mem type, num
 813               Same as top, except sorted by mem usage instead of cpu
 814
 815
 816        totalup net
 817               Total upload, this one too, may overflow
 818
 819
 820        updates Number of updates
 821               for debugging
 822
 823
 824        upspeed net
 825               Upload speed in kilobytes
 826
 827
 828        upspeedf net
 829               Upload speed in kilobytes with one decimal
 830
 831
 832        upspeedgraph  net (height),(width) (gradient colour 1) (gradient colour
 833        2) (scale)
 834               Upload  speed  graph,  colours  defined  in hex, minus the #. If
 835               scale is non-zero, it becomes the scale for the graph.
 836
 837
 838        uptime Uptime
 839
 840
 841        uptime_short
 842               Uptime in a shorter format
 843
 844
 845        seti_prog
 846               Seti@home current progress
 847
 848
 849        seti_progbar (height),(width)
 850               Seti@home current progress bar
 851
 852
 853        seti_credit
 854               Seti@home total user credit
 855
 856
 857        voffset (pixels)
 858               Change verticle offset by N pixels. Negative values  will  cause
 859               text to overlap. See also $offset.
 860
 861
 862 EXAMPLES
 863        conky -t '${time %D %H:%m}' -o -u 30
 864               Start Conky in its own window with date and clock as text and 30
 865               sec update interval.
 866
 867        conky -a top_left -x 5 -y 500 -d
 868               Start Conky to background at coordinates (5, 500).
 869
 870 FILES
 871        ~/.conkyrc default configuration file
 872
 873 BUGS
 874        Drawing to root or some other desktop window directly doesn't work with
 875        all window managers. Especially doesn't work well with Gnome and it has
 876        been reported that it doesn't work with KDE  either.  Nautilus  can  be
 877        disabled  from  drawing  to  desktop with program gconf-editor. Uncheck
 878        show_desktop in /apps/nautilus/preferences/.  There  is  -w  switch  in
 879        Conky  to  set  some  specific window id. You might find xwininfo -tree
 880        useful to find the window to draw to. You  can  also  use  -o  argument
 881        which makes Conky to create its own window.
 882
 883 SEE ALSO
 884        http://conky.sourceforge.net [http://conky.sourceforge.net]
 885
 886        http://www.sourceforge.net/projects/conky           [http://www.source-
 887        forge.net/projects/conky]
 888
 889        #conky on irc.freenode.net
 890
 891 AUTHORS
 892        The Conky dev team. What's up now!
 893
 894
 895
 896                                   2005-10-17                          conky(1)