i3blocks.1

.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "I3BLOCKS" "1" "July 2014" "" ""
.
.SH "NAME"
\fBi3blocks\fR \- define blocks for your i3bar status line
.
.SH "SYNOPSIS"
\fBi3blocks\fR [\-c \fIconfigfile\fR] [\-d \fIscriptsdir\fR] [\-h] [\-v]
.
.SH "DESCRIPTION"
\fBi3blocks\fR generates a status line for i3bar(1)\. It handles clicks, signals and user scripts\.
.
.SH "OPTIONS"
.
.TP
\fB\-c\fR \fIconfigfile\fR
Specifies an alternate configuration file path\. By default, i3blocks looks for configuration files in the following order:
.
.IP "" 4
.
.nf

1\. ~/\.config/i3blocks/config (or $XDG_CONFIG_HOME/i3blocks/config if set)
2\. ~/\.i3blocks\.conf
3\. /etc/i3blocks\.conf or /usr/local/etc/i3blocks\.conf
.
.fi
.
.IP "" 0

.
.TP
\fB\-d\fR \fIscriptsdir\fR
Specifies an alternate directory to set the $BLOCK_LIBEXEC variable to\. By default, i3blocks set this variable to its compile\-time value\. The priorities are (higher first):
.
.IP "" 4
.
.nf

1\. The value of this <scriptsdir> argument
2\. Compile\-time value: /usr/libexec/i3blocks or /usr/local/libexec/i3blocks
.
.fi
.
.IP "" 0

.
.TP
\fB\-v\fR
Print the version and exit\.
.
.TP
\fB\-h\fR
Print the help message and exit\.
.
.SH "CONFIGURATION"
The configuration file is an ini file\. Each section describes a new block\. A line beginning with a \fB#\fR sign is a comment, and empty lines are ignored\. A property is a \fBkey=value\fR pair per line, with no space around the equal sign\. Properties declared outside a block (i\.e\. at the beginning of the file) describe global settings\.
.
.P
Here is an example config file:
.
.IP "" 4
.
.nf

# This is a comment
interval=5
color=#00FF00

[weather]
command=~/bin/weather\.pl
interval=1800

[time]
command=date +%T
.
.fi
.
.IP "" 0
.
.P
To use i3blocks as your status line, define it in a \fIbar\fR block of your \fB~/i3/config\fR file:
.
.IP "" 4
.
.nf

bar {
  status_command i3blocks
}
.
.fi
.
.IP "" 0
.
.SH "BLOCK"
The properties used to describe a block are the keys specified in the i3bar protocol \fIhttp://i3wm\.org/docs/i3bar\-protocol\.html\fR, plus additional properties used by \fBi3blocks\fR to describe when and how to update a block\. All the supported properties are described below\.
.
.P
The following keys are standard, see http://i3wm\.org/docs/i3bar\-protocol\.html \fI\fR for details\.
.
.IP "\(bu" 4
\fBfull_text\fR
.
.IP "\(bu" 4
\fBshort_text\fR
.
.IP "\(bu" 4
\fBcolor\fR
.
.IP "\(bu" 4
\fBmin_width\fR
.
.IP "\(bu" 4
\fBalign\fR
.
.IP "\(bu" 4
\fBname\fR
.
.IP "\(bu" 4
\fBinstance\fR
.
.IP "\(bu" 4
\fBurgent\fR
.
.IP "\(bu" 4
\fBseparator\fR
.
.IP "\(bu" 4
\fBseparator_block_width\fR
.
.IP "" 0
.
.P
The following keys are specific to \fBi3blocks\fR\.
.
.TP
\fBcommand\fR
The command executed by a shell, used to update the block\. The expected behavior is described below, in the \fICOMMAND\fR section\.
.
.TP
\fBinterval\fR
The time in second to wait before updating the block\. If 0, the block won\'t be updated again\.
.
.TP
\fBsignal\fR
The signal number used to update the block\. For instance, \fBsignal=10\fR means that this block will be updated when \fBi3blocks\fR receives a SIGUSR1\. Currently, SIGUSR1 and SIGUSR2 are supported\.
.
.SH "COMMAND"
The value of the \fBcommand\fR key will be passed and executed as is by a shell\.
.
.P
The standard output of the command line is used to update the block content\. Each non\-empty line of the output will overwrite the corresponding property:
.
.IP "1." 4
full_text
.
.IP "2." 4
short_text
.
.IP "3." 4
color
.
.IP "" 0
.
.P
For example, this script sets the \fBfull_text\fR in blue but no \fBshort_text\fR:
.
.IP "" 4
.
.nf

echo "Here\'s my label"
echo
echo \e#0000FF
.
.fi
.
.IP "" 0
.
.P
If the command line returns 0 or 33, the block is updated\. Otherwise, it is considered a failure and the first line (if any) is still displayed\. Note that stderr is ignored\. A return code of 33 will set the \fBurgent\fR flag to true\.
.
.P
For example, this script prints the battery percentage and sets the urgent flag if it is below 10%:
.
.IP "" 4
.
.nf

BAT=`acpi \-b | grep \-E \-o \'[0\-9][0\-9]?%\'`

echo "BAT: $BAT"
test ${BAT%?} \-le 10 && exit 33 || exit 0
.
.fi
.
.IP "" 0
.
.P
When forking a block command, \fBi3blocks\fR will set the environment with some \fBBLOCK_*\fR variables\. The following variables are always provided, with eventually an empty string as the value\.
.
.TP
\fBBLOCK_NAME\fR
The name of the block (usually the section name)\.
.
.TP
\fBBLOCK_INSTANCE\fR
An optional argument to the script\.
.
.TP
\fBBLOCK_BUTTON\fR
Mouse button (1, 2 or 3) if the block was clicked\.
.
.TP
\fBBLOCK_X\fR and \fBBLOCK_Y\fR
Coordinates where the click occured, if the block was clicked\.
.
.TP
\fBBLOCK_LIBEXEC\fR
A variable optionally used to locate a scripts directory\.
.
.P
Here is an example using the environment:
.
.IP "" 4
.
.nf

[block]
command=echo name=$BLOCK_NAME instance=$BLOCK_INSTANCE
interval=1

[clickme]
command=echo button=$BLOCK_BUTTON x=$BLOCK_X y=$BLOCK_Y
min_width=button=1 x=1366 y=768
align=left
.
.fi
.
.IP "" 0
.
.P
Note that \fBi3blocks\fR provides a set of optional scripts for convenience, such as network status, battery check, cpu load, volume, etc\.
.
.SH "EXAMPLES"
As an example, here is a close configuration to i3status(1) default settings:
.
.P
\fBTODO\fR
.
.IP "" 4
.
.nf

interval=5
signal=10

[ipv6]

[free]

[dhcp]

[vpn]

[wifi]

[ethernet]
min_width=E: 255\.255\.255\.255 (1000 Mbit/s)

[battery]

[cpu]

[datetime]
.
.fi
.
.IP "" 0
.
.P
The following block shows the usage of \fBsignal\fR with some i3(1) bindings which adjust the volume, before issuing a \fBkillall \-USR1 i3blocks\fR:
.
.IP "" 4
.
.nf

[volume]
command=echo \-n \'Volume: \'; amixer get Master | grep \-E \-o \'[0\-9][0\-9]?%\'
signal=10
# no interval, only check on SIGUSR1
.
.fi
.
.IP "" 0
.
.P
Here is an example of a very minimalist config, assuming you have a bunch of scripts under \fB~/bin/blocks/\fR with the same name as the blocks:
.
.IP "" 4
.
.nf

command=~/bin/blocks/$BLOCK_NAME
interval=1

[free]
[wifi]
[ethernet]
[battery]
[cpu]
[datetime]
.
.fi
.
.IP "" 0
.
.SH "SEE ALSO"
The development of i3blocks takes place on Github \fIhttps://github\.com/vivien/i3blocks\fR\. The wiki \fIhttps://github\.com/vivien/i3blocks/wiki\fR is a good source of examples for blocks and screenshots\.
.
.P
i3(1), i3bar(1), i3status(1)
.
.SH "BUGS"
.
.SS "Reporting Bugs"
Please report bugs on the issue tracker \fIhttps://github\.com/vivien/i3blocks/issues\fR\.
.
.SS "Known Bugs"
None\.
.
.SH "AUTHOR"
Written by Vivien Didelot \fIvivien\.didelot@gmail\.com\fR\.
.
.SH "COPYRIGHT"
Copyright (C) 2014 Vivien Didelot \fIvivien\.didelot@gmail\.com\fR License GPLv3+: GNU GPL version 3 or later \fIhttp://gnu\.org/licenses/gpl\.html\fR\.
.
.P
This is free software: you are free to change and redistribute it\. There is NO WARRANTY, to the extent permitted by law\.