1 .de Vb \" Begin verbatim text 2 .ft CW 3 .nf 4 .ne \\$1 5 .. 6 .de Ve \" End verbatim text 7 .ft R 8 .fi 9 .. 10 11 .TH i3lock-color 1 "JAN 2022" Linux "User Manuals" 12 13 .SH NAME 14 i3lock-color \- improved screen locker 15 16 .SH SYNOPSIS 17 .B i3lock 18 .RB [\|\-v\|] 19 .RB [\|\-n\|] 20 .RB [\|\-b\|] 21 .RB [\|\-i 22 .IR image.png \|] 23 .RB [\|\-c 24 .IR color \|] 25 .RB [\|\-t\|] 26 .RB [\|\-p 27 .IR pointer\|] 28 .RB [\|\-u\|] 29 .RB [\|\-e\|] 30 .RB [\|\-f\|] 31 .RB [\|\-m\|] 32 33 .SH DESCRIPTION 34 .B i3lock\-color 35 is a simple screen locker like slock. After starting it, you will see a white 36 screen (you can configure the color/an image). You can return to your screen by 37 entering your password. 38 39 .SH FEATURES 40 .IP \[bu] 2 41 i3lock forks, so you can combine it with an alias to suspend to RAM 42 (run "i3lock && echo mem > /sys/power/state" to get a locked screen after waking 43 up your computer from suspend to RAM) 44 .IP \[bu] 45 You can specify either a background color or a PNG image which will be displayed 46 while your screen is locked. 47 .IP \[bu] 48 You can specify whether i3lock should bell upon a wrong password. 49 .IP \[bu] 50 i3lock uses PAM and therefore is compatible with LDAP, etc. 51 52 .SH OPTIONS 53 .TP 54 .B \-v, \-\-version 55 Display the version of your 56 .B i3lock 57 58 .TP 59 .B \-n, \-\-nofork 60 Don't fork after starting. 61 62 .TP 63 .B \-b, \-\-beep 64 Enable beeping. Be sure to not do this when you are about to annoy other people, 65 like when opening your laptop in a boring lecture. 66 67 .TP 68 .B \-u, \-\-no\-unlock\-indicator 69 Disable the unlock indicator. i3lock will by default show an unlock indicator 70 after pressing keys. This will give feedback for every keypress and it will 71 show you the current PAM state (whether your password is currently being 72 verified or whether it is wrong). 73 74 .TP 75 .BI \-i\ path \fR,\ \fB\-\-image= path 76 Display the given PNG image instead of a blank screen. 77 78 .TP 79 .BI \fB\-\-raw= format 80 Read the image given by \-\-image as a raw image instead of PNG. The argument is 81 the image's format as <width>x<height>:<pixfmt>. 82 The supported pixel formats are: 83 \'native', 'rgb', 'xrgb', 'rgbx', 'bgr', 'xbgr', and 'bgrx'. 84 The "native" pixel format expects a pixel as a 32-bit (4-byte) integer in 85 the machine's native endianness, with the upper 8 bits unused. 86 Red, green and blue are stored in the remaining bits, in that order. 87 88 .BR Example: 89 .Vb 6 90 \& --raw=1920x1080:rgb 91 .Ve 92 You can use ImageMagick’s 93 .IR convert(1) 94 program to feed raw images into i3lock: 95 96 .Vb 6 97 \& convert wallpaper.jpg RGB:- | i3lock --raw 3840x2160:rgb --image /dev/stdin 98 .Ve 99 This allows you to load a variety of image formats without i3lock having to 100 support each one explicitly. 101 You can also use it to resize images to the screen ratio: 102 103 .Vb 6 104 \& convert wallpaper.jpg -resize $(xdpyinfo | grep dimensions | sed -r 's/^[^0-9]*([0-9]+x[0-9]+).*$/\1/') RGB:- | i3lock --raw $(xdpyinfo | grep dimensions | sed -r 's/^[^0-9]*([0-9]+x[0-9]+).*$/\1/'):rgb --image /dev/stdin 105 .Ve 106 Note that $(xdpyinfo | grep dimensions | sed -r 's/^[^0-9]*([0-9]+x[0-9]+).*$/\1/') 107 gets you the current screen dimensions in the wxh (e.g. 1920x1080) format. 108 109 .TP 110 .BI \-c\ rrggbbaa \fR,\ \fB\-\-color= rrggbbaa 111 Turn the screen into the given color instead of white. Color must be given in 112 4-byte format: rrggbbaa (i.e. ff0000ff is opaque red). 113 Use the last byte for alpha. Setting this below FF (i.e. ff000088) will allow 114 your screen to be shown translucently if you use a compositor (e.g. compton, 115 xcompmgr). 116 117 .TP 118 .B \-t, \-\-tiling 119 If an image is specified (via \-i) it will display the image tiled all over the 120 screen. 121 122 Note: For all image options, with a multi-monitor setup, the image is visible on 123 all screens. 124 125 .TP 126 .B \-C, \-\-centered 127 If an image is specified (via \-i) it will display the image centered on the 128 screen. 129 130 .TP 131 .B \-F, \-\-fill 132 If an image is specified (via \-i) it will scale the image until it fills the 133 screen. A portion of the image will be cropped. 134 135 .TP 136 .B \-M, \-\-max 137 If an image is specified (via \-i) it will scale the image until either the 138 width or the height fits the screen without being cropped. The border color 139 can be set via \-c. 140 141 .TP 142 .B \-L, \-\-scale 143 If an image is specified (via \-i) it will stretch the image until both the 144 width and the height fits the screen. 145 146 .TP 147 .BI \-p\ win|default \fR,\ \fB\-\-pointer= win|default 148 If you specify "default", 149 .B i3lock 150 does not hide your mouse pointer. If you specify "win", 151 .B i3lock 152 displays a hardcoded Windows-Pointer (thus enabling you to mess with your 153 friends by using a screenshot of a Windows desktop as a locking-screen). 154 155 .TP 156 .B \-e, \-\-ignore\-empty\-password 157 When an empty password is provided by the user, do not validate it. Without this 158 option, the empty password will be provided to PAM and, if invalid, the user 159 will have to wait a few seconds before another try. This can be useful if the 160 XF86ScreenSaver key is used to put a laptop to sleep and bounce on resume or if 161 you happen to wake up your computer with the enter key. 162 163 .TP 164 .B \-f, \-\-show\-failed\-attempts 165 Show the number of failed attempts, if any. 166 167 .TP 168 .B \-\-debug 169 Enables debug logging. 170 Note, that this will log the password used for authentication to stdout. 171 172 .SH i3lock-color OPTIONS 173 .TP 174 .B \-S number, \-\-screen=number 175 Specifies which display to draw the unlock indicator and clock on. By default, 176 they'll be placed on every screen. 177 Note that this number is zero indexed. The ordering is dependent on libxinerama. 178 179 .TP 180 .B \-B sigma, \-\-blur=sigma 181 Captures the screen and blurs it using the given sigma (radius). 182 Images may still be overlaid over the blurred screenshot. 183 As an alternative to this option, you could specify a translucent background 184 color (-c option) with a fully transparent or translucent color, and use a 185 compositor to perform blurring (e.g. compton, picom). 186 187 .TP 188 .B \-k, \-\-clock, \-\-force\-clock 189 Displays the clock. \-\-force\-clock also displays the clock when there's 190 indicator text (useful for when the clock is not positioned with the indicator). 191 192 .TP 193 .B \-\-indicator 194 Forces the indicator to always be visible, instead of only showing on activity. 195 196 .TP 197 .B \-\-radius 198 The radius of the circle. Defaults to 90. 199 200 .TP 201 .B \-\-ring\-width 202 The width of the ring unlock indicator. Defaults to 7.0. 203 204 .TP 205 .B \-\-{inside, ring}\-color=rrggbbaa 206 Sets the idle color for the interior circle and ring. Note: use individual 207 options per element unless the shell supports brace expansion (in which case 208 remove the spaces inside the curly braces). 209 210 .TP 211 .B \-\-{inside, ring}ver\-color=rrggbbaa 212 Sets the interior circle and ring color while the password is being verified. 213 214 .TP 215 .B \-\-{inside, ring}wrong\-color=rrggbbaa 216 Sets the interior circle and ring color for during incorrect password flashes. 217 218 .TP 219 .B \-\-line\-color=rrggbbaa 220 Sets the color for the line separating the inside circle and the outer ring. 221 222 .TP 223 .B \-\-line\-uses\-{inside, ring} 224 Overrides \-\-line\-color. The line will match the {inside, ring} color. 225 Note: these two options conflict with each other. 226 227 .TP 228 .B \-\-{key, bs}hl\-color=rrggbbaa 229 Sets the color of highlight arcs on the ring upon keypress and backspace. 230 231 .TP 232 .B \-\-separator\-color=rrggbbaa 233 Sets the color of the seperators at both ends of the highlight arcs on the ring. 234 235 .TP 236 .B \-\-{verif, wrong, modif}\-color=rrggbbaa 237 Sets the color of the status text while verifying and when password is wrong. 238 239 .TP 240 .B \-\-{layout, time, date, greeter}\-color=rrggbbaa 241 Sets text colors. 242 243 .TP 244 .B \-\-keylayout mode 245 Displays the keylayout. Positionable similar to date, time, and indicator. 246 Modes are as follows: 247 .RS 248 .IP \[bu] 2 249 0 - Displays the full string returned by the query, i.e. "English (US)" 250 .IP \[bu] 251 1 - Displays up until the first parenthesis, i.e. "English" 252 .IP \[bu] 253 2 - Displays just the contents of the parenthesis, i.e. "US" 254 .RE 255 256 .B For all following -str or -text options, some control characters 257 .B (i.e. \\\\n, \\\\t) are supported. See \fBCONTROL CHARACTERS\fR 258 .B for more details. 259 260 .TP 261 .B \-\-time\-str="%H:%M:%S" 262 Sets the format used for generating the time string. 263 See strftime(3) for a full list of format specifiers. 264 265 .TP 266 .B \-\-date\-str="%A, %m %Y" 267 Sets the format used for generating the date string. 268 269 .TP 270 .B \-\-verif\-text="verifying…" 271 Sets the string to be shown while verifying the password/input/key/etc. 272 273 .TP 274 .B \-\-wrong\-text="wrong!" 275 Sets the string to be shown upon entering an incorrect password. 276 277 .TP 278 .B \-\-noinput\-text="no input" 279 Sets the string to be shown upon pressing backspace without anything to delete. 280 281 .TP 282 .B \-\-lock\-text="locking…" 283 Sets the string to be shown while acquiring pointer and keyboard focus. 284 285 .TP 286 .B \-\-lockfailed\-text="lock failed!" 287 Sets the string to be shown after failing to acquire pointer and keyboard focus. 288 289 .TP 290 .B \-\-greeter\-text="" 291 Sets the greeter text. 292 293 .TP 294 .B \-\-no\-modkey\-text 295 Hides the modkey indicator (Num, Caps Lock ...) 296 297 .TP 298 .B \-\-{time, date, layout, verif, wrong, modif, greeter}\-align 299 Sets the text alignment of the time, date, keylayout, verification, wrong, 300 modifier and greeter texts. 301 .RS 302 .IP \[bu] 2 303 0 - centered (default) 304 .IP \[bu] 305 1 - left aligned 306 .IP \[bu] 307 2 - right aligned 308 .RE 309 310 .TP 311 .B \-\-{time, date, layout, verif, wrong, greeter, modif}outline\-color=rrggbbaa 312 Sets the color of the outlines. 313 314 .TP 315 .B \-\-{time, date, layout, verif, wrong, greeter}\-font=sans\-serif 316 Sets the font used to render various strings. 317 318 .TP 319 .B \-\-{time, date, layout, verif, wrong, greeter}\-size=number 320 Sets the font size used to render various strings. 321 322 .TP 323 .B \-\-{time, date, layout, verif, wrong, greeter, modifier}outline\-width=number 324 Sets the width of the outline. 325 326 .TP 327 .B \-\-ind\-pos="x\-position:y\-position" 328 Sets the position for the unlock indicator. Valid variables include: 329 .RS 330 .IP \[bu] 2 331 x - x position of the current display. 332 Corresponds to the leftmost column of pixels on that display. 333 .IP \[bu] 334 y - y position of the current display. 335 Corresponds to the topmost row of pixels on that display. 336 .IP \[bu] 337 w - width of the current display. 338 .IP \[bu] 339 h - height of the current display. 340 .IP \[bu] 341 r - unlock indicator radius. 342 .RE 343 344 .TP 345 .B \-\-time\-pos="x\-position:y\-position" 346 Sets the position for the time string. All the variables from \-\-ind\-pos may 347 be used, in addition to: 348 .RS 349 .IP \[bu] 2 350 ix - x position of the indicator on the current display. 351 .IP \[bu] 352 iy - y position of the indicator on the current display. 353 354 If the \-\-bar\-indicator option is used, the following variables may be used: 355 .IP \[bu] 2 356 bw - width of the bar indicator. 357 .IP \[bu] 358 bx - x position of the bar indicator on the current display. 359 .IP \[bu] 360 by - y position of the bar indicator on the current display. 361 .RE 362 363 .TP 364 .B \-\-date\-pos="x\-position:y\-position" 365 Sets the position for the date string. All the variables from \-\-ind\-pos and 366 \-\-time\-pos may be used, in addition to: 367 .RS 368 .IP \[bu] 2 369 tx - x position of the timestring on the current display. 370 .IP \[bu] 371 ty - y position of the timestring on the current display. 372 .RE 373 374 .TP 375 .B \-\-greeter\-pos="x\-position:y\-position" 376 Sets the position for the greeter string. All the variables from \-\-ind\-pos and 377 \-\-time\-pos may be used. 378 379 .TP 380 .B \-\-pass\-{media, screen, power, volume}\-keys 381 Allow the following keys to be used normally while the screen is locked by 382 passing them through: 383 .RS 384 .IP \[bu] 2 385 media - XF86AudioPlay, XF86AudioPause, XF86AudioStop, XF86AudioPrev, 386 XF86AudioNext, XF86AudioMute, XF86AudioLowerVolume, XF86AudioRaiseVolume, 387 XF86AudioMicMute 388 .IP \[bu] 389 screen - XF86MonBrightnessUp, XF86MonBrightnessDown 390 .IP \[bu] 391 power - XF86PowerDown, XF86PowerOff, XF86Sleep 392 .IP \[bu] 393 volume - XF86AudioMute, XF86AudioLowerVolume, XF86AudioRaiseVolume 394 .RE 395 396 397 .TP 398 .B \-\-custom\-key\-commands 399 Enables custom shell commands for media, screen, power and volume keys. An alternative to \-\-pass\-media\0keys that will work in any environment. 400 401 .TP 402 .B \-\-cmd\-** 403 Shell command to run when the corresponding key is pressed. Requires \-\-custom\-key\-commands 404 .RS 405 .IP \[bu] 2 406 brightness\-up - XF86MonBrightnessUp 407 .IP \[bu] 408 brightness\-down - XF86MonBrightnessDown 409 .IP \[bu] 410 media\-play - XF86AudioPlay 411 .IP \[bu] 412 media\-pause - XF86AudioPause 413 .IP \[bu] 414 media\-stop - XF86AudioStop 415 .IP \[bu] 416 media\-next - XF86AudioNext 417 .IP \[bu] 418 media\-prev - XF86AudioPrev 419 .IP \[bu] 420 audio\-mute - XF86AudioMute 421 .IP \[bu] 422 volume\-up - XF86AudioRaiseVolume 423 .IP \[bu] 424 volume\-down - XF86AudioLowerVolume 425 .IP \[bu] 426 mic\-mute - XF86AudioMicMute 427 .IP \[bu] 428 power\-down - XF86PowerDown 429 .IP \[bu] 430 power\-off - XF86PowerOff 431 .IP \[bu] 432 power\-sleep - XF86Sleep 433 .RE 434 435 .TP 436 .B \-\-bar\-indicator 437 Replaces the usual ring indicator with a bar indicator. Comes with perks. 438 439 .TP 440 .B \-\-bar\-direction={0, 1, 2} 441 Sets the direction the bars grow in. 0 is the default (downwards, or rightwards, 442 depending on the bar orientation). 1 is the reverse, and 2 is both. 443 444 .TP 445 .B \-\-bar\-orientation={vertical,horizontal} 446 Sets whether the bar is vertically or horizontally oriented. 447 Defaults to horizontal. 448 449 .TP 450 .B \-\-bar\-step 451 Sets the step that each bar decreases by when a key is pressed. A random bar is 452 set to its max height, then each neighbor is set to (height - step*distance). 453 454 .TP 455 .B \-\-bar\-max\-height 456 The maximum height a bar can get to. When a key is pressed, a random bar is set 457 to this value, then its neighbors are set to its height, minus the step value. 458 459 .TP 460 .B \-\-bar\-base\-width 461 The thickness of the "base" bar that all the bars originate from. 462 This bar also takes on the ring verification and wrong colors to give 463 authentication feedback. 464 465 .TP 466 .B \-\-bar\-color 467 Sets the default color of the bar base. 468 469 .TP 470 .B \-\-bar\-periodic\-step 471 The value by which the bars decrease each time the screen is redrawn. 472 473 .TP 474 .B \-\-bar\-pos 475 Works similarly to the time/date/indicator expressions. If only one number is 476 provided, this sets the vertical offset from the top or left edge. If two 477 numbers are provided in the form of x:y, sets the starting position of the bar. 478 479 .TP 480 .B \-\-bar\-count 481 Sets the number of minibars to draw on each screen. 482 483 .TP 484 .B \-\-bar\-total\-width 485 The total width of the bar. Can be an expression. 486 487 .TP 488 .B \-\-redraw\-thread 489 Starts a separate thread for redrawing the screen. Potentially worse from a 490 security standpoint, but makes the bar indicator still do its usual periodic 491 redraws when PAM is authenticating. 492 493 .TP 494 .B \-\-refresh\-rate=seconds\-as\-double 495 The refresh rate of the indicator, given in seconds. This should automatically 496 align itself, but is somewhat buggy currently. 497 Values less than one will work, but may result in poor system performance. 498 499 .TP 500 .B \-\-composite 501 Some compositors have problems with i3lock trying to render over them, so this 502 argument is disabled by default. However, some will work properly with it, so 503 it's been left enabled. 504 505 .TP 506 .B \-\-no\-verify 507 Do not verify the password entered by the user and unlock immediately. 508 .B Use only for quickly testing new configurations and remember to remove to 509 .B actually lock your screen! 510 511 .TP 512 .B \-\-slideshow\-interval 513 The interval to wait until switching to the next image. 514 515 .TP 516 .B \-\-slideshow\-random\-selection 517 Randomize the order of the images. 518 519 .SH CONTROL CHARACTERS 520 Control characters (\\r \\n \\b \\t) are supported in text OPTIONS. Their behavior 521 are almost as same as anywhere else. 522 .TP 523 .B Carriage Return(\\\\r) 524 Move to the start of line (left edge). 525 Notes: The rendered characters would still live there. 526 .TP 527 .B Line Feed(\\\\n) 528 Move to start of next line (left edge). 529 .TP 530 .B Backspace(\\\\b) 531 Overwrite last one char if exists. 532 Notes: The rendered character would still live there. 533 .TP 534 .B Tab(\\\\t) 535 Move to next tab stop position.The width of one character for moving is as same as character 'a'. 536 Note: The width may be strange if the font is not mono-spaced. 537 538 .SH SEE ALSO 539 .IR xautolock(1) 540 \- use i3lock as your screen saver 541 542 .IR convert(1) 543 \- feed a wide variety of image formats to i3lock 544 545 .SH HOMEPAGE 546 https://github.com/Raymo111/i3lock-color 547 548 Please report bugs and submit pull-requests as follows: 549 For i3lock (upstream): https://github.com/i3/i3lock 550 For i3lock-color (enhancements on top of i3lock): https://github.com/Raymo111/i3lock-color 551 552 .SH AUTHORS 553 Michael Stapelberg <michael+i3lock at stapelberg dot de> 554 555 Jan-Erik Rediger <badboy at archlinux.us> 556 557 Pandora <pandora at techfo dot xyz> 558 559 Raymond Li <i3lock-color at raymond.li>
