### Example s6-usertree-maker for s6-rc Integration

Source: https://github.com/skarnet/s6/blob/main/doc/s6-usertree-maker.html

This example shows s6-usertree-maker creating s6-rc source definition directories for a service and its logger, along with an implicit bundle. Similar to the previous example, it utilizes variable substitution and specifies logging configuration.

```shell
s6-usertree-maker -d '/run/user/${UID}/service' -p '${HOME}/bin:/usr/bin:/bin' -E /etc/user-env -e XDG_CONFIG_HOME -l catchlog -r usertree-ska/usertree-ska-log/usertree-ska-pipeline ska /var/log/usertree/ska usertree
```

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

### Complete s6 Service Example

Source: https://context7.com/skarnet/s6/llms.txt

This example demonstrates the directory structure and `run` scripts for a complete s6 service, including environment variable handling, resource limiting, privilege dropping, and logging integration.

```bash
# Directory structure for a complete service with logging:
#
# /etc/sv/myapp/
# ├── run
# ├── finish
# ├── notification-fd
# ├── env/
# │   ├── DATABASE_URL
# │   └── PORT
# └── log/
#     └── run

# /etc/sv/myapp/run:
#!/bin/execlineb -P
fdmove -c 2 1
s6-envdir /etc/sv/myapp/env
s6-softlimit -o 1024 -m 268435456
s6-setuidgid myapp
/usr/bin/myapp --foreground --notify-fd 3

# /etc/sv/myapp/notification-fd:
3

# /etc/sv/myapp/finish:
#!/bin/sh
# $1 = exit code (or 256 if killed by signal)
# $2 = signal number (if killed by signal)
# $3 = service directory name
logger "myapp exited with code $1"

# /etc/sv/myapp/log/run:
#!/bin/execlineb -P
s6-setuidgid log
s6-log -b n20 s1000000 t /var/log/myapp

# Scan directory setup:
mkdir -p /run/service
ln -s /etc/sv/myapp /run/service/myapp
```

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

### Example s6-usertree-maker Command Usage

Source: https://github.com/skarnet/s6/blob/main/doc/s6-usertree-maker.html

This example demonstrates how to use s6-usertree-maker to create a service directory with variable substitution for PATH and environment variables. It also configures logging via s6-log. Note the use of simple quotes to prevent shell interpretation of special variables.

```shell
s6-usertree-maker -d '/run/user/${UID}/service' -p '${HOME}/bin:/usr/bin:/bin' -E /etc/user-env -e XDG_CONFIG_HOME -l catchlog ska /var/log/usertree/ska usertree-ska
```

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

### Start s6-ftrigr Session (ftrigr_start)

Source: https://github.com/skarnet/s6/blob/main/doc/libs6/ftrigr.html

Initializes a session with an s6-ftrigrd service listening on a specified path. Requires an ftrigr_t structure initialized to FTRIGR_ZERO, and accurate timestamps for deadline and stamp. Returns 1 on success, 0 on failure or timeout.

```c
ftrigr_t a = FTRIGR_ZERO ;
char const *path = FTRIGR_IPCPATH ;
tain_t deadline, stamp ;

tain_now(&stamp) ;
tain_addsec(&deadline, &stamp, 2) ;
ftrigr_start(&a, path, &deadline, &stamp) ;

```

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

### Start s6-ftrigr Session (ftrigr_startf)

Source: https://github.com/skarnet/s6/blob/main/doc/libs6/ftrigr.html

Initializes a session with an s6-ftrigrd process as a child. Requires an ftrigr_t structure initialized to FTRIGR_ZERO, and accurate timestamps for deadline and stamp. Returns 1 on success, 0 on failure or timeout.

```c
ftrigr_t a = FTRIGR_ZERO ;
tain_t deadline, stamp ;

tain_now(&stamp) ;
tain_addsec(&deadline, &stamp, 2) ;
ftrigr_startf(&a, &deadline, &stamp) ;

```

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

### s6-sudod Usage Example (Execline Script)

Source: https://github.com/skarnet/s6/blob/main/doc/s6-sudod.html

This example demonstrates a typical use case for s6-sudod within a service directory, utilizing other s6 tools like s6-ipcserver and s6-envdir to set up a privileged program execution environment. It involves file descriptor manipulation, privilege setting, and socket communication.

```execline
#!/command/execlineb -P
fdmove -c 2 1
fdmove 1 3
s6-envuidgid serveruser
s6-ipcserver -U -1 -- serversocket
s6-ipcserver-access -v2 -l0 -i rules --
exec -c
s6-envdir env
s6-sudod
sargv
```

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

### Run Script Redirection Example (shell)

Source: https://github.com/skarnet/s6/blob/main/doc/servicedir.html

An example of how to redirect stderr to stdout within a run script using standard shell syntax. This is a common method for consolidating output streams for logging.

```shell
exec 2>&1
```

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

### Start and End s6-fdholder Session (C)

Source: https://github.com/skarnet/s6/blob/main/doc/libs6/fdholder.html

Shows how to start a new session with an s6-fdholderd instance listening on a specific path, and how to properly end it. The `s6_fdholder_start` function returns a handle for subsequent operations, while `s6_fdholder_end` releases resources and allows the handle to be reused.

```C
int s6_fdholder_start (s6_fdholder_t *a, char const *path, tain_t const *deadline, tain_t *stamp)
```

```C
void s6_fdholder_end (s6_fdholder_t *a)
```

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

### s6-instance-create Command

Source: https://github.com/skarnet/s6/blob/main/doc/s6-instance-create.html

The s6-instance-create program creates a new instance of a currently supervised instanced service. It expects a running, supervised instanced service in the specified directory and creates a new instance with the given name, optionally starting it immediately or keeping it down until later control.

```APIDOC
## s6-instance-create

### Description
Creates a new instance of a currently supervised [instanced service](instances.html).

### Method
COMMAND LINE

### Endpoint
N/A (Command Line Tool)

### Parameters
#### Path Parameters
- **servicedir** (string) - Required - The directory of the running, supervised instanced service.
- **name** (string) - Required - The name for the new instance.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
s6-instance-create /path/to/supervised/service my_new_instance
```

### Response
#### Success Response (0)
- **exit code** (integer) - 0 indicates success.

#### Error Responses
- **exit code** (integer) - 99: timeout while waiting for the instance supervisor to start.
- **exit code** (integer) - 100: wrong usage.
- **exit code** (integer) - 111: system call failed.

### Options
*   `-d` : down. The instance supervisor will be started, but the instance itself will remain down. Any down file for the instance will be deleted.
*   `-D` : down, and stay down. The instance supervisor will be started, but the instance itself will remain down. A down file will be created for the instance.
*   `-P` : public. Everyone will be able to subscribe to the instance supervisor's notification.
*   `-f` : force permissions. For testing purposes only.
*   `-t _timeout_` : if the instance supervisor has not started after _timeout_ milliseconds, s6-instance-create will print a message to stderr and exit 99. Default is 0 (no time limit).
```

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

### Session Management: ftrigr_start and ftrigr_end

Source: https://github.com/skarnet/s6/blob/main/doc/libs6/ftrigr.html

Functions for starting and ending a session with the s6-ftrigrd daemon. ftrigr_start initiates a session, either with a running daemon or by forking a new one. ftrigr_end releases all resources associated with a session.

```APIDOC
## Session Management: ftrigr_start and ftrigr_end

### Description
Manages the lifecycle of a session with the s6-ftrigrd daemon. `ftrigr_startf` starts a session by forking a new `s6-ftrigrd` process, while `ftrigr_start` connects to an existing one via a specified path. `ftrigr_end` cleans up session resources, making the `ftrigr_t` structure reusable.

### Functions
- `ftrigr_start(ftrigr_t *a, const char *path, const tain_t *deadline, const tain_t *stamp)`
- `ftrigr_startf(ftrigr_t *a, const tain_t *deadline, const tain_t *stamp)`
- `ftrigr_end(ftrigr_t *a)`

### Parameters
#### `ftrigr_start` and `ftrigr_startf` Parameters
- **a** (ftrigr_t*) - Required - The session structure to initialize, must be initialized to `FTRIGR_ZERO`.
- **path** (const char*) - Required (for `ftrigr_start`) - The path to the IPC socket for the `s6-ftrigrd` service.
- **deadline** (const tain_t*) - Required - The absolute time by which the operation must complete.
- **stamp** (const tain_t*) - Required - An accurate timestamp.

#### `ftrigr_end` Parameters
- **a** (ftrigr_t*) - Required - The session structure to close.

### Return Value
- Both `ftrigr_start` and `ftrigr_startf` return 1 on success, 0 on failure (errno is set). A return of 0 with `ETIMEDOUT` indicates the deadline was reached.
- `ftrigr_end` does not return a value.

### Usage Example
```c
tain_t deadline, stamp;
tain_now(&stamp);
tain_addsec(&deadline, &stamp, 2);

ftrigr_t session;
ftrigr_startf(&session, &deadline, &stamp);
// ... use session ...
ftrigr_end(&session);
```
```

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

### List Instances of a Service (Shell Script)

Source: https://github.com/skarnet/s6/blob/main/doc/s6-instance-list.html

This example demonstrates how to use s6-instance-list within a shell script to iterate over all instances of a service and perform an action on each. It assumes `s6-instance-list` is available in the PATH and the service directory is a valid argument.

```shell
for i in `s6-instance-list _service_` ; do printf "%s: " $i ; s6-instance-status _service_ $i ; done
```

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

### Run Script Redirection Example (execline)

Source: https://github.com/skarnet/s6/blob/main/doc/servicedir.html

An example of how to redirect stderr to stdout within a run script using the 'fdmove' command from execline. This ensures that both standard output and standard error are sent to the same pipe, typically for logging purposes.

```execline
fdmove -c 2 1
```

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

### s6-ftrig-listen Command-Line Interface (execlineb)

Source: https://github.com/skarnet/s6/blob/main/doc/s6-ftrig-listen.html

Demonstrates the basic usage of the s6-ftrig-listen command within an execlineb script. It shows how to specify fifodirs, regular expressions, and the program to be executed. The default behavior is to wait for all specified patterns to match.

```bash
s6-ftrig-listen { _fifodir1_ _regexp1_ _fifodir2_ _regexp2_ ... } _prog...
```

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

### Using s6-ftrig-listen in a Shell Script via execlineb

Source: https://github.com/skarnet/s6/blob/main/doc/s6-ftrig-listen.html

Provides an example of how to safely integrate s6-ftrig-listen into a standard shell script by using execlineb's -Pc option. This ensures correct parsing of arguments and the use of execlineb's brace syntax for defining the event patterns.

```sh
execlineb -Pc 's6-ftrig-listen ...'
```

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

### Bring Up Service and Wait for Readiness with s6-svc

Source: https://github.com/skarnet/s6/blob/main/doc/s6-svc.html

Commands the service to come up and blocks until it signals readiness or a timeout occurs. '-wU' with '-T' specifies a timeout in milliseconds, returning an error if the service is not ready within that period.

```bash
s6-svc -wU -T 5000 -u /run/service/ftpd
```

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

### Get File Descriptor for Event Monitoring (C)

Source: https://github.com/skarnet/s6/blob/main/doc/libs6/ftrigr.html

Retrieves the file descriptor that can be used with select() to monitor for incoming event data from the s6-ftrigrd daemon. This file descriptor should not be directly read from; instead, ftrigr_updateb() should be called when it becomes readable.

```c
int ftrigr_fd (ftrigr_t const *a);
```

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

### s6-svlisten Command Line Interface (Execline)

Source: https://github.com/skarnet/s6/blob/main/doc/s6-svlisten.html

This snippet shows the command-line syntax for s6-svlisten when used within an execline script. It highlights how to specify options, service directories, and the program to execute.

```bash
s6-svlisten [ -U | -u | -D | -d | -r | -R ] [ -a | -o ] [ -t _timeout_ ] { _servicedir_ _servicedir..._ } _prog..._
```

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

### Example finish script for permanent failure handling

Source: https://github.com/skarnet/s6/blob/main/doc/servicedir.html

This script shows how to signal a permanent failure for a service. If the finish script exits with the specific status code 125, s6-supervise will interpret this as a permanent failure and will not restart the service.

```shell
#!/bin/sh

# Arguments:
# $1: exit code from run script (256+ for signal)
# $2: signal number (if $1 > 255)
# $3: service directory name
# $4: process group id of the defunct run script

# Example: If the service consistently fails with a specific condition, 
# you might want to mark it as a permanent failure.
# For demonstration, let's assume a condition that leads to permanent failure.
# In a real scenario, this would depend on the exit code or other checks.

# If a specific error condition is met, exit with 125 to indicate permanent failure
# if [ some_error_condition ]; then
#   exit 125
# fi

# For this example, we'll just simulate a permanent failure scenario
exit 125
```

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

### s6-svlisten Command Line Interface (Standard)

Source: https://github.com/skarnet/s6/blob/main/doc/s6-svlisten.html

This snippet illustrates the command-line syntax for s6-svlisten outside of an execline script. It shows the structure for providing service directories and the program to run, noting the empty string separator.

```bash
s6-svlisten [ -U | -u | -D | -d | -r | -R ] [ -a | -o ] [ -t _timeout_ ] _servicedir_ _servicedir..._ "" _prog..._
```