Swaylock

https://github.com/swaywm/swaylock
Admin
Swaylock is a screen locking utility for Wayland compositors that implements the ext-session-lock-v1...
Tokens:45,696
Snippets:351
Trust Score:9.1
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### loop_create usage example

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/loop.md

Example of initializing the event loop in main.c.

```c
state.eventloop = loop_create();
```

--------------------------------

### Compile and Install swaylock from Source

Source: https://github.com/swaywm/swaylock/blob/master/README.md

Commands to build the project using meson and ninja, followed by system-wide installation.

```bash
meson build
ninja -C build
sudo ninja -C build install
```

--------------------------------

### loop_add_fd registration example

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/loop.md

Example of registering three file descriptors to the event loop in main.c.

```c
loop_add_fd(state.eventloop, wl_display_get_fd(state.display), POLLIN,
		display_in, NULL);
loop_add_fd(state.eventloop, get_comm_reply_fd(), POLLIN, comm_in, NULL);
loop_add_fd(state.eventloop, sigusr_fds[0], POLLIN, term_in, NULL);
```

--------------------------------

### Example swaylock config file

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/configuration.md

Example configuration file in long-option=value format. The '=' is required for flags that take an argument; flag options without arguments are written bare. '#' starts a comment. This example sets an image, scaling mode, shows failed attempts, and sets ring color.

```ini
# Example from swaylock.1.scd
image=/usr/share/backgrounds/sway/Sway_Wallpaper_Blue_768x1024.png
scaling=center
show-failed-attempts
ring-color=#ff00ff
```

--------------------------------

### spawn_comm_child usage example

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/comm.md

Example from shadow.c:52 showing how to call spawn_comm_child and exit on failure.

```c
if (!spawn_comm_child()) {
	exit(EXIT_FAILURE);
}
```

--------------------------------

### loop_add_timer usage example

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/loop.md

Example of setting a 10-second timer to clear the password state.

```c
state->clear_password_timer = loop_add_timer(
		state->eventloop, 10000, clear_password, state);
```

--------------------------------

### Example: using gdk_cairo_image_surface_create_from_pixbuf

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/cairo.md

Example from background-image.c:36 that applies embedded orientation and converts the pixbuf to a cairo surface.

```c
// background-image.c:36 (HAVE_GDK_PIXBUF build)
GdkPixbuf *oriented = gdk_pixbuf_apply_embedded_orientation(pixbuf);
g_object_unref(pixbuf);
image = gdk_cairo_image_surface_create_from_pixbuf(oriented);
g_object_unref(oriented);
```

--------------------------------

### Registration example (main.c:272)

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/seat.md

Binds a wl_seat, allocates a swaylock_seat, and adds the seat listener.

```c
struct wl_seat *seat = wl_registry_bind(
		registry, name, &wl_seat_interface, 4);
struct swaylock_seat *swaylock_seat =
	calloc(1, sizeof(struct swaylock_seat));
swaylock_seat->state = state;
wl_seat_add_listener(seat, &seat_listener, swaylock_seat);
```

--------------------------------

### Example: font configuration using to_cairo_subpixel_order

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/cairo.md

Example from render.c:98 that sets font options including subpixel order from the Wayland subpixel value.

```c
cairo_font_options_t *fo = cairo_font_options_create();
cairo_font_options_set_hint_style(fo, CAIRO_HINT_STYLE_FULL);
cairo_font_options_set_antialias(fo, CAIRO_ANTIALIAS_SUBPIXEL);
cairo_font_options_set_subpixel_order(fo, to_cairo_subpixel_order(subpixel));
```

--------------------------------

### Example: background fill using cairo_set_source_u32

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/cairo.md

Example from render.c:70 that sets the operator to SOURCE, applies the background color, and paints.

```c
cairo_set_operator(cairo, CAIRO_OPERATOR_SOURCE);
cairo_set_source_u32(cairo, state->args.colors.background);
cairo_paint(cairo);
```

--------------------------------

### create_buffer usage example (indicator buffer)

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/pool-buffer.md

Example from render.c:63 that creates a buffer for the frame background, logging an error and returning on failure.

```c
if (!create_buffer(state->shm, &buffer, buffer_width, buffer_height,
		WL_SHM_FORMAT_ARGB8888)) {
	swaylock_log(LOG_ERROR,
		"Failed to create new buffer for frame background.");
	return;
}
```

--------------------------------

### seat_handle_capabilities pointer and keyboard setup

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/seat.md

Shows how the capabilities handler fetches pointer and keyboard when capabilities change.

```c
if ((caps & WL_SEAT_CAPABILITY_POINTER)) {
	seat->pointer = wl_seat_get_pointer(wl_seat);
	wl_pointer_add_listener(seat->pointer, &pointer_listener, NULL);
}
if ((caps & WL_SEAT_CAPABILITY_KEYBOARD)) {
	seat->keyboard = wl_seat_get_keyboard(wl_seat);
	wl_keyboard_add_listener(seat->keyboard, &keyboard_listener, seat);
}
```

--------------------------------

### destroy_buffer usage example (surface teardown)

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/pool-buffer.md

Example from main.c:107 that destroys both indicator buffers during surface teardown.

```c
destroy_buffer(&surface->indicator_buffers[0]);
destroy_buffer(&surface->indicator_buffers[1]);
```

--------------------------------

### Append example using utf8_encode

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/unicode.md

Example from password.c:41. Appends a codepoint to the password buffer, checking for space and null-terminating.

```c
static void append_ch(struct swaylock_password *pw, uint32_t codepoint) {
	size_t utf8_size = utf8_chsize(codepoint);
	if (pw->len + utf8_size + 1 >= pw->buffer_len) {
		// TODO: Display error
		return;
	}
	utf8_encode(&pw->buffer[pw->len], codepoint);
	pw->buffer[pw->len + utf8_size] = 0;
	pw->len += utf8_size;
}
```

--------------------------------

### log_init example with debug detection (main.c)

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/log.md

Parses command-line options to enable debug logging. If -d is present, initializes with LOG_DEBUG; otherwise falls back to LOG_ERROR.

```c
void log_init(int argc, char **argv) {
	static struct option long_options[] = {
		{"debug", no_argument, NULL, 'd'},
		{0, 0, 0, 0}
	};
	int c;
	optind = 1;
	while (1) {
		int opt_idx = 0;
		c = getopt_long(argc, argv, "-:d", long_options, &opt_idx);
		if (c == -1) {
			break;
		}
		switch (c) {
		case 'd':
			swaylock_log_init(LOG_DEBUG);
			return;
		}
	}
	swaylock_log_init(LOG_ERROR);
}
```

--------------------------------

### schedule_auth_idle example: wrong-password path in comm_in

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/swaylock.md

Example from main.c:1049. Sets auth state to invalid and schedules auth idle.

```c
// wrong-password path in comm_in (main.c:1049)
state.auth_state = AUTH_STATE_INVALID;
schedule_auth_idle(&state);
```

--------------------------------

### clear_buffer example from shadow backend

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/swaylock.md

Example usage from shadow.c:58 where the buffer is only used by the child process. It wipes the encrypted password and then sets the pointer to NULL.

```c
/* Buffer is only used by the child */
clear_buffer(encpw, strlen(encpw));
encpw = NULL;
```

--------------------------------

### PAM configuration file

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/configuration.md

The default PAM configuration file installed as sysconfdir/pam.d/swaylock when libpam is detected.

```text
auth include login
```

--------------------------------

### get_next_buffer usage example (indicator frame)

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/pool-buffer.md

Example from render.c:311 that obtains a buffer from the indicator pool, logging 'No buffer' and returning false if NULL.

```c
struct pool_buffer *buffer = get_next_buffer(state->shm,
		surface->indicator_buffers, buffer_width, buffer_height);
if (buffer == NULL) {
	swaylock_log(LOG_ERROR, "No buffer");
	return false;
}
```

--------------------------------

### clear_password_buffer example: Escape key handling

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/swaylock.md

Example from password.c:159. Handles the Escape key by clearing the password buffer, setting input state to clear, cancelling password clear, scheduling input idle, and damaging state.

```c
case XKB_KEY_Escape:
	clear_password_buffer(&state->password);
	state->input_state = INPUT_STATE_CLEAR;
	cancel_password_clear(state);
	schedule_input_idle(state);
	damage_state(state);
	break;
```

--------------------------------

### Create password buffer in main

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/password-buffer.md

Example usage from main.c:1156. Sets the password buffer length to 1024, creates the buffer, and fails with EXIT_FAILURE if creation fails. The first byte is zeroed after creation.

```c
state.password.len = 0;
state.password.buffer_len = 1024;
state.password.buffer = password_buffer_create(state.password.buffer_len);
if (!state.password.buffer) {
	return EXIT_FAILURE;
}
state.password.buffer[0] = 0;
```

--------------------------------

### load_background_image usage example

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/background-image.md

Call site for load_background_image. Frees the image and returns when loading fails; otherwise inserts it into the image list.

```c
// Load the actual image
image->cairo_surface = load_background_image(image->path);
if (!image->cairo_surface) {
	free(image);
	return;
}
wl_list_insert(&state->images, &image->link);
```

--------------------------------

### Backspace example using utf8_last_size

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/unicode.md

Example from password.c:32. Decrements the password length by the size of the last UTF-8 character and null-terminates the buffer.

```c
static bool backspace(struct swaylock_password *pw) {
	if (pw->len != 0) {
		pw->len -= utf8_last_size(pw->buffer);
		pw->buffer[pw->len] = 0;
		return true;
	}
	return false;
}
```

--------------------------------

### meson.build: Define swaylock executable

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/README.md

Defines the swaylock executable in meson.build, specifying sources, include directories, dependencies, and installation.

```meson
executable('swaylock',
	sources + protos_src,
	include_directories: [swaylock_inc],
	dependencies: dependencies,
	install: true
)
```

--------------------------------

### Handling swaylock errors

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/cli.md

Example script demonstrating how to capture and inspect exit codes and error output from swaylock.

```sh
set -e
if swaylock --scaling bogus 2>/tmp/swaylock.err; then
  echo "unlocked normally"
else
  rc=$?
  echo "swaylock exited with $rc"
  # rc=1: bad flag / missing compositor globals / no WAYLAND_DISPLAY
  # rc=2: another lockscreen holds the session
  cat /tmp/swaylock.err
fi
```

--------------------------------

### loop_remove_timer usage example

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/loop.md

Example of cancelling a pending input-idle timer before scheduling a new one.

```c
static void schedule_input_idle(struct swaylock_state *state) {
	if (state->input_idle_timer) {
		loop_remove_timer(state->eventloop, state->input_idle_timer);
	}
	state->input_idle_timer = loop_add_timer(
		state->eventloop, 1500, set_input_idle, state);
}
```

--------------------------------

### Basic swaylock usage examples

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/cli.md

Common commands for locking the screen, including default behavior, background customization, keybindings, and programmatic unlocking.

```sh
# Lock with defaults
swaylock

# Lock immediately with a solid color background
swaylock --color 000000

# Per-output backgrounds with scaling
swaylock --image DP-1:/usr/share/backgrounds/left.png \
         --image '::my:path.png' \
         --scaling fill

# Typical sway/i3wm binding: ignore empty password, hide indicator
bindsym $mod+$l exec swaylock --ignore-empty-password --no-unlock-indicator

# Wait until actually locked before doing something sensitive
swaylock --ready-fd 3 3> >(read -r; echo ready >&2)

# Unlock programmatically (SIGUSR1)
swaylock &
sleep 30
kill -USR1 $!
```

--------------------------------

### parse_background_mode usage example

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/background-image.md

Call site for parse_background_mode. Aborts with exit code 1 when the mode is invalid.

```c
// main.c:576
state->args.mode = parse_background_mode(optarg);
if (state->args.mode == BACKGROUND_MODE_INVALID) {
	return 1; /* parser aborts; usage shown */
}
```

--------------------------------

### damage_state example: wrong password path in comm_in

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/swaylock.md

Example usage from main.c:1049. Sets auth state to invalid, schedules auth idle, increments failed attempts, and calls damage_state.

```c
// main.c:1049
state.auth_state = AUTH_STATE_INVALID;
schedule_auth_idle(&state);
++state.failed_attempts;
damage_state(&state);
```

--------------------------------

### Example usage of swaylock_log_errno

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/log.md

Shows how to log an error with errno. The output includes a timestamp, source file and line, and the error message from strerror.

```c
swaylock_log_errno(LOG_ERROR, "failed to create pipe");
/* => 2024-01-01 00:00:00 - [comm.c:87] failed to create pipe: Resource temporarily unavailable */
```

--------------------------------

### Using swaylock_handle_key in seat.c

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/swaylock.md

Example usage of swaylock_handle_key in the wl_keyboard.key listener in seat.c:92. It obtains the keysym and codepoint from the xkb state and calls the handler only on key press.

```c
// wl_keyboard.key listener in seat.c
xkb_keysym_t sym = xkb_state_key_get_one_sym(state->xkb.state, key + 8);
uint32_t codepoint = xkb_state_key_get_utf32(state->xkb.state,
		key_state == WL_KEYBOARD_KEY_STATE_PRESSED ? key + 8 : 0);
if (key_state == WL_KEYBOARD_KEY_STATE_PRESSED) {
	swaylock_handle_key(state, sym, codepoint);
}
```

--------------------------------

### render() usage in ext_session_lock_surface_v1 configure handler

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/swaylock.md

Example of how render() is called after updating surface dimensions and acknowledging a configure event. Sets the surface as dirty before rendering.

```c
// ext_session_lock_surface_v1 configure handler (main.c:161)
surface->width = width;
surface->height = height;
ext_session_lock_surface_v1_ack_configure(lock_surface, serial);
surface->dirty = true;
render(surface);
```

--------------------------------

### write_comm_reply usage in shadow backend

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/comm.md

Example from shadow.c:87 showing how to call write_comm_reply. On failure the child exits with EXIT_FAILURE; a sleep(2) rate-limits crypt(3) attempts.

```c
if (!write_comm_reply(success)) {
	exit(EXIT_FAILURE);
}
sleep(2); /* rate-limit crypt(3) attempts */
```

--------------------------------

### loop_poll main loop usage

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/loop.md

Example of using loop_poll within the main application loop in main.c.

```c
state.run_display = true;
while (state.run_display) {
	errno = 0;
	if (wl_display_flush(state.display) == -1 && errno != EAGAIN) {
		break;
	}
	loop_poll(state.eventloop);
}
```

--------------------------------

### Destroy password buffer after PAM authentication

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/password-buffer.md

Example from pam.c:111. After authenticating, the password buffer is destroyed and the pointers are set to NULL. The same pattern is used in shadow.c and comm.c.

```c
state.password = pw_buf;
int pam_status = pam_authenticate(auth_handle, 0);
password_buffer_destroy(pw_buf, size);
pw_buf = NULL;
state.password = NULL;
```

--------------------------------

### write_comm_request usage in submit path — password.c:110

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/comm.md

Example call in the password submission path. If the write fails, sets auth_state to AUTH_STATE_INVALID and schedules idle. Always calls damage_state afterwards. Located at password.c:110.

```c
if (!write_comm_request(&state->password)) {
	state->auth_state = AUTH_STATE_INVALID;
	schedule_auth_idle(state);
}
damage_state(state);
```

--------------------------------

### read_comm_request usage in PAM child loop

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/comm.md

Example from pam.c:107 showing how to call read_comm_request in the PAM child loop. On error (size < 0) the child exits with EXIT_FAILURE; on clean EOF (size == 0) the loop breaks.

```c
ssize_t size = read_comm_request(&pw_buf);
if (size < 0) {
	exit(EXIT_FAILURE);
} else if (size == 0) {
	break;
}
```

--------------------------------

### initialize_pw_backend

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/swaylock.md

Initializes the password backend with the given command-line arguments. This sets up the backend that will be used for password verification.

```APIDOC
## initialize_pw_backend

### Description
Initializes the password backend with the given command-line arguments. This sets up the backend that will be used for password verification.

### Function Signature
void initialize_pw_backend(int argc, char **argv);

### Parameters
- **argc** (int) - Required - The number of command-line arguments.
- **argv** (char **) - Required - The array of command-line arguments.

### Return
void
```

--------------------------------

### Declare initialize_pw_backend function

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/swaylock.md

Backend-specific startup function that verifies privileges and forks the authentication child. Defined once per backend (pam.c:13 or shadow.c:21). Never returns on failure; exits with EXIT_FAILURE.

```c
void initialize_pw_backend(int argc, char **argv);
```

--------------------------------

### Main entry point

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/cli.md

The main function signature for the swaylock application.

```c
int main(int argc, char **argv)
```

--------------------------------

### Early initialization helpers

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/cli.md

Helper functions invoked before full argument parsing to initialize logging and the password backend.

```c
void log_init(int argc, char **argv)   // main.c:1068
void initialize_pw_backend(int argc, char **argv)  // pam.c:13 | shadow.c:21
```

--------------------------------

### Include swaylock.h

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/swaylock.md

Include the central header that pulls in background-image.h, cairo.h, pool-buffer.h, and seat.h. Consumers include this header plus whichever module headers they need.

```c
#include "swaylock.h"
```

--------------------------------

### loop_create

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/loop.md

Creates a new event loop with an initial file descriptor capacity of 10 and empty event and timer lists. Returns NULL on allocation failure.

```APIDOC
## loop_create

### Description
Creates a new event loop with an initial file descriptor capacity of 10 and empty event and timer lists. Returns NULL on allocation failure.

### Function Signature
```c
struct loop *loop_create(void);
```

### Parameters
None.

### Return Value
- `struct loop *` - A pointer to the newly allocated loop, or `NULL` on allocation failure.

### Example
```c
state.eventloop = loop_create();
```
```

--------------------------------

### Declare run_pw_backend_child function

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/swaylock.md

Child-side authentication loop executed after fork() in spawn_comm_child (comm.c:105). Terminates the child process.

```c
void run_pw_backend_child(void);
```

--------------------------------

### Include loop.h header

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/loop.md

Include the event loop header file in your project.

```c
#include "loop.h"
```

--------------------------------

### Function declarations from swaylock.h

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/swaylock.md

Declarations from include/swaylock.h:113 for the six global functions implemented in main.c, password.c, render.c, and the password backends.

```c
void swaylock_handle_key(struct swaylock_state *state,
		xkb_keysym_t keysym, uint32_t codepoint);

void render(struct swaylock_surface *surface);
void damage_state(struct swaylock_state *state);
void clear_password_buffer(struct swaylock_password *pw);
void schedule_auth_idle(struct swaylock_state *state);

void initialize_pw_backend(int argc, char **argv);
void run_pw_backend_child(void);
void clear_buffer(char *buf, size_t size);
```

--------------------------------

### Include pool-buffer.h

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/pool-buffer.md

Include the pool-buffer.h header to use the buffer pool functions.

```c
#include "pool-buffer.h"
```

--------------------------------

### Include cairo.h header

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/cairo.md

Include the cairo.h header file for swaylock's cairo helpers.

```c
#include "cairo.h"
```

--------------------------------

### cairo_set_source_u32 implementation

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/cairo.md

Shows the internal implementation that unpacks the color components and calls cairo_set_source_rgba.

```c
cairo_set_source_rgba(cairo,
		(color >> (3*8) & 0xFF) / 255.0,
		(color >> (2*8) & 0xFF) / 255.0,
		(color >> (1*8) & 0xFF) / 255.0,
		(color >> (0*8) & 0xFF) / 255.0);
```

--------------------------------

### read_comm_reply usage in event-loop handler — main.c:1041

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/comm.md

Example usage in the event loop. On POLLIN, reads the reply: exits with failure on read error, unlocks on success (run_display=false), otherwise marks auth_state invalid, schedules idle, increments failed_attempts and damages state. On POLLHUP/POLLERR logs that the subprocess crashed and exits.

```c
if (mask & POLLIN) {
	bool auth_success = false;
	if (!read_comm_reply(&auth_success)) {
		exit(EXIT_FAILURE);
	}
	if (auth_success) {
		state.run_display = false; /* unlock */
	} else {
		state.auth_state = AUTH_STATE_INVALID;
		schedule_auth_idle(&state);
		++state.failed_attempts;
		damage_state(&state);
	}
} else if (mask & (POLLHUP | POLLERR)) {
	swaylock_log(LOG_ERROR,
		"Password checking subprocess crashed; exiting.");
	exit(EXIT_FAILURE);
}
```

--------------------------------

### Include unicode.h

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/unicode.md

Include the header for UTF-8 helper functions.

```c
#include "unicode.h"
```

--------------------------------

### Configure suid Permissions for swaylock

Source: https://github.com/swaywm/swaylock/blob/master/README.md

Set the suid bit on the swaylock binary for systems where passwords are stored in /etc/shadow and PAM is not used.

```bash
sudo chmod a+s /usr/local/bin/swaylock
```

--------------------------------

### Include password-buffer.h

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/password-buffer.md

Include the password-buffer header to access the password buffer API.

```c
#include "password-buffer.h"
```

--------------------------------

### swaylock_log_init

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/log.md

Initializes the logging system with a verbosity filter level. Values greater than or equal to LOG_IMPORTANCE_LAST are ignored.

```APIDOC
## swaylock_log_init

### Description
Initializes the logging system with a verbosity filter level. Values greater than or equal to LOG_IMPORTANCE_LAST are ignored.

### Function Signature
void swaylock_log_init(enum log_importance verbosity);

### Parameters
- **verbosity** (enum log_importance) - Required - New filter level. Values >= LOG_IMPORTANCE_LAST are ignored.

### Return
void

### Example
```c
void log_init(int argc, char **argv) {
	static struct option long_options[] = {
		{"debug", no_argument, NULL, 'd'},
		{0, 0, 0, 0}
	};
	int c;
	optind = 1;
	while (1) {
		int opt_idx = 0;
		c = getopt_long(argc, argv, "-:d", long_options, &opt_idx);
		if (c == -1) {
			break;
		}
		switch (c) {
		case 'd':
			swaylock_log_init(LOG_DEBUG);
			return;
		}
	}
	swaylock_log_init(LOG_ERROR);
}
```
```

--------------------------------

### password_buffer_create prototype

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/password-buffer.md

Prototype for password_buffer_create, which allocates a page-aligned, mlocked buffer of the given size.

```c
char *password_buffer_create(size_t size);
```

--------------------------------

### Include background-image.h

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/background-image.md

Include the background-image header to access the background mode enum and image loading functions.

```c
#include "background-image.h"
```

--------------------------------

### create_buffer function signature

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/pool-buffer.md

Allocates a fresh anonymous shm region and wraps it as a wl_buffer plus cairo surface.

```c
struct pool_buffer *create_buffer(struct wl_shm *shm, struct pool_buffer *buf,
	int32_t width, int32_t height, uint32_t format);
```

--------------------------------

### Password buffer API prototypes

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/password-buffer.md

Function prototypes for creating and destroying a secure password buffer.

```c
char *password_buffer_create(size_t size);
void password_buffer_destroy(char *buffer, size_t size);
```

--------------------------------

### gdk_cairo_image_surface_create_from_pixbuf declaration

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/cairo.md

Declares the function under a preprocessor guard for HAVE_GDK_PIXBUF builds.

```c
#if HAVE_GDK_PIXBUF

cairo_surface_t* gdk_cairo_image_surface_create_from_pixbuf(
		const GdkPixbuf *gdkbuf);

#endif // HAVE_GDK_PIXBUF
```

--------------------------------

### loop_create function signature

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/loop.md

Signature for creating a new event loop instance.

```c
struct loop *loop_create(void);
```

--------------------------------

### Call render_background_image at render.c:73

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/background-image.md

Call site from render.c:73 that sets the operator to CAIRO_OPERATOR_OVER and invokes render_background_image with the lock-surface background context, the loaded image, the configured mode, and the buffer dimensions.

```c
cairo_set_operator(cairo, CAIRO_OPERATOR_OVER);
render_background_image(cairo, surface->image,
	state->args.mode, buffer_width, buffer_height);
```

--------------------------------

### Logging macros swaylock_log and swaylock_log_errno

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/log.md

swaylock_log prepends [file:line] to the message, while swaylock_log_errno appends the strerror(errno) text. Both require fmt to have a conversion for each extra argument.

```c
#define swaylock_log(verb, fmt, ...) \
	_swaylock_log(verb, "[%s:%d] " fmt, _swaylock_strip_path(__FILE__), \
			__LINE__, ##__VA_ARGS__)

#define swaylock_log_errno(verb, fmt, ...) \
	swaylock_log(verb, fmt ": %s", ##__VA_ARGS__, strerror(errno))
```

--------------------------------

### Declare render_background_image function

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/background-image.md

Function declaration for painting an image into a buffer with a given scaling mode. The function wraps its work in cairo_save/cairo_restore and ends with cairo_paint. The image must not be NULL from load_background_image; SOLID_COLOR and INVALID modes trigger assert(0).

```c
void render_background_image(cairo_t *cairo, cairo_surface_t *image,
		enum background_mode mode, int buffer_width, int buffer_height);
```

--------------------------------

### damage_state behavior: iterate surfaces and render

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/swaylock.md

Shows the implementation of damage_state: iterates over the state's surfaces list, sets each surface's dirty flag, and calls render.

```c
wl_list_for_each(surface, &state->surfaces, link) {
	surface->dirty = true;
	render(surface);
}
```

--------------------------------

### load_background_image declaration

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/background-image.md

Declares the function that decodes an image file into a cairo surface. Returns NULL on failure.

```c
cairo_surface_t *load_background_image(const char *path);
```

--------------------------------

### run_pw_backend_child

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/swaylock.md

Runs the password backend child process. This is the entry point for the child process that handles password verification.

```APIDOC
## run_pw_backend_child

### Description
Runs the password backend child process. This is the entry point for the child process that handles password verification.

### Function Signature
void run_pw_backend_child(void);

### Parameters
None

### Return
void
```

--------------------------------

### Include logging header (log.h)

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/log.md

Includes the logging module header. This is required to use any logging functions or macros defined in log.h.

```c
#include "log.h"
```

--------------------------------

### load_background_image

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/background-image.md

Decodes an image file into a cairo surface. Returns NULL on any failure.

```APIDOC
## load_background_image

### Description
Decodes an image file into a cairo surface. Returns NULL on any failure.

### Function Signature
```c
cairo_surface_t *load_background_image(const char *path);
```

### Parameters
- `path` (const char *) - Required - Filesystem path (already `wordexp`-expanded by `load_image`).

### Behavior
- With `HAVE_GDK_PIXBUF` (gdk-pixbuf built): `gdk_pixbuf_new_from_file(path, &err)`; on failure logs `"Failed to load background image (%s)."` with `err->message` and returns `NULL`. Then applies EXIF orientation (`gdk_pixbuf_apply_embedded_orientation`) and converts via `gdk_cairo_image_surface_create_from_pixbuf`.
- Without gdk-pixbuf: `cairo_image_surface_create_from_png(path)`; failure logs `"Failed to read background image."`.
- Both paths then check `cairo_surface_status(image) != CAIRO_STATUS_SUCCESS`, logging `"Failed to read background image: %s."` plus, without gdk-pixbuf, the hint `"Sway was compiled without gdk_pixbuf support, so only PNG images can be loaded. This is the likely cause."` and returning `NULL`.

### Return
`cairo_surface_t *` - The decoded image, or `NULL` on any failure. Callers must handle `NULL`; `load_image` frees the whole `struct swaylock_image` and skips insertion.

### Example (call site, main.c:389)
```c
// Load the actual image
image->cairo_surface = load_background_image(image->path);
if (!image->cairo_surface) {
	free(image);
	return;
}
wl_list_insert(&state->images, &image->link);
```
```

--------------------------------

### Configure sgid Permissions for swaylock

Source: https://github.com/swaywm/swaylock/blob/master/README.md

Set the sgid bit on the swaylock binary for systems where /etc/shadow is owned by the shadow group.

```bash
sudo chgrp shadow /usr/local/bin/swaylock
sudo chmod g+s /usr/local/bin/swaylock
```

--------------------------------

### parse_background_mode declaration

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/background-image.md

Parses the --scaling string. Returns BACKGROUND_MODE_INVALID for unsupported values and logs an error.

```c
enum background_mode parse_background_mode(const char *mode);
```

--------------------------------

### loop_add_fd

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/loop.md

Registers a file descriptor with the event loop, specifying an event mask and a callback function to be invoked when the descriptor becomes ready. The callback receives the ready fd, the event mask, and user-provided data.

```APIDOC
## loop_add_fd

### Description
Registers a file descriptor with the event loop, specifying an event mask and a callback function to be invoked when the descriptor becomes ready. The callback receives the ready fd, the event mask, and user-provided data.

### Function Signature
void loop_add_fd(struct loop *loop, int fd, short mask, void (*func)(int fd, short mask, void *data), void *data);

### Parameters
- **loop** (struct loop *) - Required - Target loop.
- **fd** (int) - Required - File descriptor to watch.
- **mask** (short) - Required - poll() event mask (e.g. POLLIN).
- **func** (void (*)(int fd, short mask, void *data)) - Required - Callback invoked with the ready fd, pfd.revents (including forced POLLHUP/POLLERR), and data.
- **data** (void *) - Required - Callback argument.

### Return
void. Allocation failure logs "Unable to allocate memory for event" and returns without registering.

### Example (registering the three watch fds, main.c:1238)
```c
loop_add_fd(state.eventloop, wl_display_get_fd(state.display), POLLIN, display_in, NULL);
loop_add_fd(state.eventloop, get_comm_reply_fd(), POLLIN, comm_in, NULL);
loop_add_fd(state.eventloop, sigusr_fds[0], POLLIN, term_in, NULL);
```
```

--------------------------------

### wl_pointer_set_cursor to hide cursor

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/seat.md

Hides the cursor on pointer enter by setting a NULL cursor.

```c
wl_pointer_set_cursor(wl_pointer, serial, NULL, 0, 0);
```

--------------------------------

### struct swaylock_args definition

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/types.md

The swaylock_args structure aggregates runtime configuration settings populated from the CLI and configuration files.

```c
struct swaylock_args {
	struct swaylock_colors colors;
	enum background_mode mode;
	char *font;
	uint32_t font_size;
	uint32_t radius;
	uint32_t thickness;
	uint32_t indicator_x_position;
	uint32_t indicator_y_position;
	bool override_indicator_x_position;
	bool override_indicator_y_position;
	bool ignore_empty;
	bool show_indicator;
	bool show_caps_lock_text;
	bool show_caps_lock_indicator;
	bool show_keyboard_layout;
	bool hide_keyboard_layout;
	bool show_failed_attempts;
	bool daemonize;
	int ready_fd;
	bool indicator_idle_visible;
};
```

--------------------------------

### password_buffer_create

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/password-buffer.md

Creates a page-aligned, mlocked buffer for password storage. Allocates memory using posix_memalign and attempts to lock it with mlock, retrying on EAGAIN and gracefully handling EPERM.

```APIDOC
## password_buffer_create

### Description
Creates a page-aligned, mlocked buffer for password storage. Allocates memory using posix_memalign and attempts to lock it with mlock, retrying on EAGAIN and gracefully handling EPERM.

### Function Signature
char *password_buffer_create(size_t size);

### Parameters
- **size** (size_t) - Required - Requested capacity in bytes.

### Behavior
1. posix_memalign(&buffer, get_page_size(), size) - the buffer is page-aligned (required by mlock-region semantics). On failure sets errno = result (posix_memalign does not set errno) and logs "failed to alloc password buffer".
2. password_buffer_lock(buffer, size) - calls mlock(addr, size) with up to 5 retries on EAGAIN; other errno values log "Unable to mlock() password memory." and fail. Special case EPERM (locked memory not permitted): logs "Unable to mlock() password memory: Unsupported!", sets mlock_supported = false, and succeeds so the program can still run without mlock privilege.
3. Returns the buffer.

### Return
char * - usable zero-initialized buffer (from calloc-like semantics of posix_memalign? - the memory is not zeroed by posix_memalign; the caller writes immediately, and main() sets buffer[0] = 0, main.c:1161), or NULL on allocation/mlock failure.

### Example (main, main.c:1156)
```c
state.password.len = 0;
state.password.buffer_len = 1024;
state.password.buffer = password_buffer_create(state.password.buffer_len);
if (!state.password.buffer) {
	return EXIT_FAILURE;
}
state.password.buffer[0] = 0;
```
```

--------------------------------

### Opaque structure declarations

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/loop.md

Forward declarations for the loop and timer structures.

```c
struct loop;
struct loop_timer;
```

--------------------------------

### Register reply fd with loop_add_fd

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/comm.md

Registers the reply fd from get_comm_reply_fd() in the event loop with POLLIN and the comm_in callback.

```c
loop_add_fd(state.eventloop, get_comm_reply_fd(), POLLIN, comm_in, NULL);
```

--------------------------------

### gdk_cairo_image_surface_create_from_pixbuf

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/cairo.md

Converts a GdkPixbuf into a premultiplied cairo image surface. Available only when built with gdk-pixbuf (HAVE_GDK_PIXBUF).

```APIDOC
## gdk_cairo_image_surface_create_from_pixbuf

### Description
Converts a `GdkPixbuf` into a premultiplied cairo image surface. Available only when built with gdk-pixbuf (`HAVE_GDK_PIXBUF`); declared under a preprocessor guard.

### Method
Function call

### Signature
```c
#if HAVE_GDK_PIXBUF

cairo_surface_t* gdk_cairo_image_surface_create_from_pixbuf(
		const GdkPixbuf *gdkbuf);

#endif // HAVE_GDK_PIXBUF
```

### Parameters
- `gdkbuf` (const GdkPixbuf *) - Required - Source pixbuf.

### Behavior
- `gdk_pixbuf_get_n_channels(gdkbuf)` must be ≥ 3, else returns `NULL`.
- `gdk_pixbuf_read_pixels` must succeed, else `NULL`.
- Creates a `CAIRO_FORMAT_RGB24` (3 channels) or `CAIRO_FORMAT_ARGB32` (4 channels) image surface of the pixbuf size; failure → `NULL`.
- For RGB: channel-swaps BGR→RGB per `G_BYTE_ORDER`.
- For RGBA: premultiplies alpha using the `PREMUL_ALPHA` macro (`(z + (z >> 8)) >> 8` rounding, `cairo.c:87`), also endianness-aware.
- Marks the surface dirty before returning.

### Return
`cairo_surface_t *` — premultiplied cairo image, or `NULL`. Used by `load_background_image` (`background-image.c:37`).

### Example
```c
// background-image.c:36 (HAVE_GDK_PIXBUF build)
GdkPixbuf *oriented = gdk_pixbuf_apply_embedded_orientation(pixbuf);
g_object_unref(pixbuf);
image = gdk_cairo_image_surface_create_from_pixbuf(oriented);
g_object_unref(oriented);
```
```

--------------------------------

### struct swaylock_xkb definition

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/seat.md

Defines the xkb state structure holding caps lock, control, and xkb state/context/keymap.

```c
struct swaylock_xkb {
	bool caps_lock;
	bool control;
	struct xkb_state *state;
	struct xkb_context *context;
	struct xkb_keymap *keymap;
};
```

--------------------------------

### Protocol wire format summary

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/comm.md

Describes the wire format for communication between parent and child processes, including frame structure and processing behavior.

```APIDOC
## Protocol wire format summary

### Description
Defines the frame structure for password communication between parent and child processes.

### Direction: parent → child
- Frame: size_t size (= len+1) then size bytes of NUL-terminated UTF-8 password

### Direction: child → parent
- Frame: 1 byte: 0x00 (fail) or 0x01 (success)

### Behavior
- Child processes one request per reply; after one success it stops processing queued requests (pam.c:129, shadow.c:91).
- The shadow child sleeps 2 seconds between attempts; there is no rate limit in the PAM backend itself.
- Ownership: request buffers are mlocked and must be released with password_buffer_destroy(buf, size) (see api-reference/password-buffer.md).

```

--------------------------------

### struct swaylock_image

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/types.md

Represents an image configuration, with one instance per -i/--image argument or image= config line.

```c
// There is exactly one swaylock_image for each -i argument
struct swaylock_image {
	char *path;
	char *output_name;
	cairo_surface_t *cairo_surface;
	struct wl_list link;
};
```

--------------------------------

### password_buffer_destroy prototype

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/password-buffer.md

Prototype for password_buffer_destroy, which wipes, unlocks, and frees the buffer.

```c
void password_buffer_destroy(char *buffer, size_t size);
```

--------------------------------

### render_background_image

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/background-image.md

Paints a background image into a cairo buffer using the specified scaling mode. The function wraps its work in cairo_save/cairo_restore and ends with cairo_paint.

```APIDOC
## render_background_image

### Description
Paints `image` into a buffer sized `buffer_width` × `buffer_height` using the given `mode`. All painting uses the current cairo state; the function wraps its work in `cairo_save`/`cairo_restore` and ends with `cairo_paint`.

### Function Signature
```c
void render_background_image(cairo_t *cairo, cairo_surface_t *image,
		enum background_mode mode, int buffer_width, int buffer_height);
```

### Parameters
- `cairo` (cairo_t *) - Required - Destination context (the lock-surface background context at the call site).
- `image` (cairo_surface_t *) - Required - Source image (must not be the `NULL` from `load_background_image`).
- `mode` (enum background_mode) - Required - Scaling strategy; `SOLID_COLOR`/`INVALID` hit `assert(0)`.
- `buffer_width` (int) - Required - Destination width in buffer px (output px × scale).
- `buffer_height` (int) - Required - Destination height.

### Per-mode behavior
- `STRETCH` - `cairo_scale(w_buf/w, h_buf/h)`; source at `(0,0)`.
- `FILL` - Uniform scale to cover; crops overflow; centres the crop.
- `FIT` - Uniform scale to fit; letterboxes.
- `CENTER` - No scale; integer-aligned to avoid blur for odd-sized images.
- `TILE` - `cairo_pattern_create_for_surface` + `CAIRO_EXTEND_REPEAT`.
- `SOLID_COLOR` / `INVALID` - `assert(0)` — unreachable from valid configuration; the renderer skips images under `SOLID_COLOR`.

### Return
`void`.

### Example (call site)
```c
cairo_set_operator(cairo, CAIRO_OPERATOR_OVER);
render_background_image(cairo, surface->image,
	state->args.mode, buffer_width, buffer_height);
```
```

--------------------------------

### render() function declaration

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/swaylock.md

Declares the render function that redraws a per-output surface. It takes a pointer to a swaylock_surface and returns void.

```c
void render(struct swaylock_surface *surface);
```

--------------------------------

### get_next_buffer function signature

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/pool-buffer.md

Hands out the next non-busy buffer from a 2-deep pool, recreating it when its size no longer matches.

```c
struct pool_buffer *get_next_buffer(struct wl_shm *shm,
	struct pool_buffer pool[static 2], uint32_t width, uint32_t height);
```

--------------------------------

### Include comm.h header

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/comm.md

Includes the comm.h header for the IPC functions.

```c
#include "comm.h"
```

--------------------------------

### swaylock_log_init function declaration

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/log.md

Declares the function that sets the logging filter level. Values greater than or equal to LOG_IMPORTANCE_LAST are ignored.

```c
void swaylock_log_init(enum log_importance verbosity);
```

--------------------------------

### _swaylock_strip_path function declaration

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/log.md

Declares the helper that strips leading './' from a file path, typically used on __FILE__.

```c
const char *_swaylock_strip_path(const char *filepath);
```

--------------------------------

### cairo_set_source_u32 function signature

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/cairo.md

Declares the function that sets the cairo source color from a packed 0xAARRGGBB value.

```c
void cairo_set_source_u32(cairo_t *cairo, uint32_t color);
```

--------------------------------

### _swaylock_log core logging function declaration

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/log.md

Declares the core logging function with printf-style format. Messages with verbosity greater than the current filter are dropped. Requires _ATTRIB_PRINTF compatibility.

```c
void _swaylock_log(enum log_importance verbosity, const char *format, ...)
	_ATTRIB_PRINTF(2, 3);
```

--------------------------------

### enum input_state

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/types.md

Represents the status of the password buffer and typing activity. It decays to INPUT_STATE_IDLE via a 1.5s timer and drives highlight rendering.

```c
enum input_state {
	INPUT_STATE_IDLE, // nothing happening; other states decay to this after time
	INPUT_STATE_CLEAR, // displaying message: password buffer was cleared
	INPUT_STATE_LETTER, // pressed a key that input a letter
	INPUT_STATE_BACKSPACE, // pressed backspace and removed a letter
	INPUT_STATE_NEUTRAL, // pressed a key (like Ctrl) that did nothing
};
```

--------------------------------

### swaylock_handle_key prototype

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/swaylock.md

Prototype for swaylock_handle_key, which processes one keyboard event against the password state machine. Defined in password.c:137.

```c
void swaylock_handle_key(struct swaylock_state *state,
		xkb_keysym_t keysym, uint32_t codepoint);
```

--------------------------------

### Logging Macros

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/log.md

Convenience macros that add source location and errno information to log messages. swaylock_log prepends [file:line] and swaylock_log_errno appends the strerror output.

```APIDOC
## Logging Macros

### Description
Convenience macros that add source location and errno information to log messages. swaylock_log prepends [file:line] and swaylock_log_errno appends the strerror output.

### Macro Definitions
#define swaylock_log(verb, fmt, ...) \
	_swaylock_log(verb, "[%s:%d] " fmt, _swaylock_strip_path(__FILE__), \
			__LINE__, ##__VA_ARGS__)

#define swaylock_log_errno(verb, fmt, ...) \
	swaylock_log(verb, fmt ": %s", ##__VA_ARGS__, strerror(errno))

### Usage
Both macros require exactly the given argument shapes - fmt must contain a printf conversion for each extra argument.

### Example
```c
swaylock_log_errno(LOG_ERROR, "failed to create pipe");
/* => 2024-01-01 00:00:00 - [comm.c:87] failed to create pipe: Resource temporarily unavailable */
```
```

--------------------------------

### keyboard_repeat function

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/seat.md

Handles key repeat by adding a timer and calling swaylock_handle_key with the repeat symbol and codepoint.

```c
static void keyboard_repeat(void *data) {
	struct swaylock_seat *seat = data;
	struct swaylock_state *state = seat->state;
	seat->repeat_timer = loop_add_timer(
		state->eventloop, seat->repeat_period_ms, keyboard_repeat, seat);
	swaylock_handle_key(state, seat->repeat_sym, seat->repeat_codepoint);
}
```

--------------------------------

### utf8_size declaration

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/unicode.md

Returns the size of the next UTF-8 character.

```c
int utf8_size(const char *str);
```

--------------------------------

### spawn_comm_child declaration

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/comm.md

Declares the spawn_comm_child function that creates pipes and forks the child process.

```c
bool spawn_comm_child(void);
```

--------------------------------

### render

Source: https://github.com/swaywm/swaylock/blob/master/_autodocs/api-reference/swaylock.md

Renders the given swaylock surface. This function is responsible for drawing the lock screen content onto the surface.

```APIDOC
## render

### Description
Renders the given swaylock surface. This function is responsible for drawing the lock screen content onto the surface.

### Function Signature
void render(struct swaylock_surface *surface);

### Parameters
- **surface** (struct swaylock_surface *) - Required - The surface to render.


### Return
void
```
Tokens:
Raw