### Example: Refreshing Package Catalog with Authentication

Source: https://github.com/illumos/ipd/blob/master/ipd/0025/README.adoc

An example demonstrating the 'pfexec pkg refresh' command, which prompts for authentication when an 'Software Installation' profile is required. It shows the interaction including password entry and successful catalog refresh.

```shell
bob@bloody:~% pfexec pkg refresh
Authentication required for 'Software Installation' profile
Password:
Refreshing catalog 2/2 openindiana.org

```

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

### Example nvmeadm Command for Writing Controller Identification Data

Source: https://github.com/illumos/ipd/blob/master/ipd/0037/README.md

This example demonstrates how to use the `nvmeadm` tool to save the identification data of an NVMe controller to a file. This is useful for later offline analysis or sharing device information.

```shell
# nvmeadm identify-controller -w /tmp/nvme0.out
```

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

### Example: Checking Command-Specific Profiles

Source: https://github.com/illumos/ipd/blob/master/ipd/0025/README.adoc

An example using 'profiles -vXlc' to check profiles applicable to the '/usr/bin/id' command for a specific user 'bob'. It displays the profile name and the command path associated with it.

```shell
bob@bloody:~% profiles -vXlc /usr/bin/id bob
bob:
      xtest (Authentication required)
          /usr/bin/id                uid=0

```

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

### SMF Managed Paths XML Configuration Example

Source: https://github.com/illumos/ipd/blob/master/ipd/0017/README.md

An example of the XML structure for the 'managed_paths' section within an SMF service manifest. It demonstrates how to define directories with various attributes like path, empty, env, mode, user, and group.

```xml
<managed_paths>
	<directory path="/var/run/foobar" empty=true />
	<directory path="/var/db/mydb-%i" env="DB_PATH" />
        <directory path="/var/tmp/unreadable" mode=0000 user="noaccess" group="noaccess" />
</managed_paths>
```

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

### Example Filesystem Layout for Distribution-Specific Files

Source: https://github.com/illumos/ipd/blob/master/ipd/0044/README.adoc

This example illustrates a potential filesystem layout for distributing files specific to different illumos distributions. It shows how distribution-specific binaries, like a dtrace helper, can be placed under /usr/dist/ or /dist, with a default fallback mechanism.

```text
usr/dist/
    default/
        bin/
	    dtrace-anon-helper -> /bin/true
    openindiana/
        bin/
	    dtrace-anon-helper -> ../../../default/bin/dtrace-anon-helper
    helios/
        bin/
	    dtrace-anon-helper
```

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

### Example: Executing 'id' with and without 'pfexec'

Source: https://github.com/illumos/ipd/blob/master/ipd/0025/README.adoc

Compares the output of the '/usr/bin/id' command when executed directly versus when executed with 'pfexec'. The 'pfexec' version requires authentication for the 'Auth pfexec test' profile and shows root user information.

```shell
bob@bloody:~% /usr/bin/id
uid=101(bob) gid=1(other)

bob@bloody:~% pfexec /usr/bin/id
Authentication required for 'Auth pfexec test' profile
Password:
uid=0(root) gid=1(other)

```

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

### Example: Using a Static Function in a Test Module (C)

Source: https://github.com/illumos/ipd/blob/master/ipd/0020/README.adoc

Demonstrates the typical pattern for accessing and using a static function from a module under test. It involves obtaining a module handle, resolving the function pointer, executing the function, and releasing the module handle.

```c
typedef boolean_t (*mac_sw_cksum_ipv4_t)(mblk_t *, uint32_t, ipha_t *,
    const char **);

void
mac_sw_cksum_ipv4_tcp_test(ktest_ctx_hdl_t *ctx)
{
	ddi_modhandle_t hdl = NULL;
	mac_sw_cksum_ipv4_t mac_sw_cksum_ipv4 = NULL;

	<... snip ...>

	if (ktest_hold_mod("mac", &hdl) != 0) {
		KT_ERROR(ctx, "failed to hold 'mac' module");
		return;
	}

	if (ktest_get_fn(hdl, "mac_sw_cksum_ipv4",
	   (void **)&mac_sw_cksum_ipv4) != 0) {
		KT_ERROR(ctx, "failed to resolve symbol %s`%s",
		    "mac", "mac_sw_cksum_ipv4");
		goto cleanup;
	}

	<... snip ...>

	KT_ASSERTG(mac_sw_cksum_ipv4(mp, ehsz, ip, &err), ctx, cleanup);

	<... snip ...>

cleanup:
	if (hdl != NULL) {
		ktest_release_mod(hdl);
	}

	<... snip ...>
}
```

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

### Partially-Qualified Test Triple Examples

Source: https://github.com/illumos/ipd/blob/master/ipd/0020/README.adoc

Examples of partially-qualified test triples, which use wildcards or incomplete specifications to match multiple test cases.

```text
*
```

```text
*:*:*
```

```text
mac:
```

```text
mac:checksum
```

```text
mac:*:mac_sw*
```

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

### Register Kernel Tests with ktest Facility (C)

Source: https://context7.com/illumos/ipd/llms.txt

This C code demonstrates the initialization (`_init`) function for a kernel test module. It shows how to create a test module, create test suites, add individual tests to suites, and register the module and its suites with the ktest facility, enabling them to be discovered and run.

```c
// _init callback - register tests with ktest facility
int
_init(void)
{
    ktest_module_hdl_t *km = NULL;
    ktest_suite_hdl_t *ks = NULL;

    // Create test module
    if (ktest_create_module("mac_test", "mac", &km) != 0) {
        return (EINVAL);
    }

    // Create test suite
    if (ktest_create_suite("checksum", &ks) != 0) {
        return (EINVAL);
    }

    // Add tests to suite
    if (ktest_add_test(ks, "mac_sw_cksum_ipv4_tcp_test",
        mac_sw_cksum_ipv4_tcp_test, KTF_NONE) != 0) {
        return (EINVAL);
    }

    if (ktest_add_test(ks, "mac_sw_cksum_ipv4_bad_proto_test",
        mac_sw_cksum_ipv4_bad_proto_test, KTF_NONE) != 0) {
        return (EINVAL);
    }

    // Add suite to module
    if (ktest_add_suite(km, ks) != 0) {
        return (EINVAL);
    }

    // Register module with ktest
    ktest_register_module(km);

    return (mod_install(&modlinkage));
}

```

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

### Fully-Qualified Test Triple Example

Source: https://github.com/illumos/ipd/blob/master/ipd/0020/README.adoc

An example of a fully-qualified test triple, which uniquely identifies a single test case by specifying all three levels of the namespace.

```text
mac:checksum:mac_sw_cksum_ipv4_tcp_test
```

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

### C Module Implementation for Custom Boot Operations

Source: https://github.com/illumos/ipd/blob/master/ipd/0052/README.adoc

Provides a template for implementing a custom boot image operations module in C. It includes standard module initialization and cleanup functions, along with placeholder functions for `custom_boot_locate` and `custom_boot_populate`. This allows developers to inject custom boot logic.

```c
#include <sys/boot_image_ops.h>

/*
 * Linkage structures
 */
static struct modlmisc custom_boot_modlmisc = {
        .misc_modops =          &mod_miscops,
        .misc_linkinfo =        "custom_boot",
};

static struct modlinkage custom_boot_modlinkage = {
        .ml_rev =               MODREV_1,
        .ml_linkage =           { &custom_boot_modlmisc, NULL },
};

int
_init(void)
{
        return (mod_install(&custom_boot_modlinkage));
}

int
_fini(void)
{
        return (mod_remove(&custom_boot_modlinkage));
}

int
_info(struct modinfo *mi)
{
        return (mod_info(&custom_boot_modlinkage, mi));
}

static void
custom_boot_locate(void)
{
        /*
         * Custom code to implement boot image location logic, just prior
         * to vfs_mountroot(), would go here.  This entrypoint is able to
         * choose which file system to use.
         */
}

static void
custom_boot_populate(void)
{
        /*
         * Custom code that runs right after the root file system is mounted
         * as per earlier direction from the locate routine.  This routine
         * is called prior to discarding the boot archive and making the root
         * file system visible to the rest of the system.
         */
}

boot_image_ops_t _boot_image_ops = {
        .bimo_version =         BOOT_IMAGE_OPS_VERSION,
        .bimo_locate =          custom_boot_locate,
        .bimo_populate =        custom_boot_populate,
};

```

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

### Example of Code Requiring smatch Adjustments (C)

Source: https://github.com/illumos/ipd/blob/master/ipd/0002/README.md

This C code snippet demonstrates a construct that might require adjustments or specific handling by smatch. The macro definition `elink_cb_get_friendly_name(cb) ''` is an example of code that uncovered peculiarities needing smatch changes or selective disabling.

```c
#define elink_cb_get_friendly_name(cb) ''
```

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

### HBA API for Initializing SCSI Packets - tran_setup_pkt

Source: https://github.com/illumos/ipd/blob/master/ipd/0033/README.md

This C function is part of the interface for initializing SCSI packets in Host Bus Adapters (HBAs). It is designed to be simpler to use than older methods and handles complexities like DMA mapping. Drivers should prefer this over tran_init_pkt.

```c
int prefix_tran_setup_pkt(struct scsi_pkt *pkt,
            int (*callback) (caddr_t), caddr_t arg);
```

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

### SCSI HBA Packet Initialization Interfaces

Source: https://github.com/illumos/ipd/blob/master/ipd/0032/README.md

This snippet shows the two primary interfaces for initializing SCSI packets in HBAs: tran_setup_pkt and tran_init_pkt. tran_setup_pkt is recommended for newer drivers due to its simplicity and the HBA framework's handling of complex DMA mapping. tran_init_pkt is the legacy interface that is more complex to use.

```c
int prefix_tran_setup_pkt(struct scsi_pkt *pkt,
     int (*callback) (caddr_t), caddr_t arg);

struct scsi_pkt *prefixtran_init_pkt(struct scsi_address *ap,
     struct scsi_pkt *pkt, struct buf *bp, int cmdlen,
     int statuslen, int tgtlen, intflags, int (*callback, caddr_t),
     caddr_t arg);
```

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

### userattr Command for Managing User Attributes

Source: https://github.com/illumos/ipd/blob/master/ipd/0025/README.adoc

The userattr command allows direct manipulation of user attribute key-value pairs. Examples demonstrate retrieving 'profiles' and 'auth_profiles' for a specific user.

```shell
% userattr profiles bob
Zone Management
% userattr auth_profiles bob
Software Installation,Service Management

```

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

### C ktest Assertions for Testing

Source: https://context7.com/illumos/ipd/llms.txt

A C code example demonstrating advanced test assertions within the ktest framework. It shows object initialization, context message prepending for better error reporting, and the use of ASSERTB blocks for cleanup on assertion failure.

```c
void
array_invariant_test(ktest_ctx_hdl_t *ctx)
{
    obj_t objs[10];

    // Initialize objects
    for (int i = 0; i < 10; i++) {
        objs[i].o_state = malloc(sizeof(state_t));
    }

    // Test with context messages
    for (int i = 0; i < 10; i++) {
        obj_t *obj = &objs[i];

        // Prepend context for better error messages
        ktest_msg_prepend(ctx, "objs[%d]: ", i);
        KT_ASSERT3P(obj->o_state, !=, NULL, ctx);
    }

    ktest_msg_clear(ctx);

    // Cleanup with ASSERTB block
    KT_ASSERT3UB(objs[0].o_count, >, 5, ctx) {
        // Cleanup code runs if assertion fails
        for (int i = 0; i < 10; i++) {
            free(objs[i].o_state);
        }
    }
    KT_ASSERTB_END

    KT_PASS(ctx);
}
```

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

### Example: Failed Authentication for 'pkg refresh'

Source: https://github.com/illumos/ipd/blob/master/ipd/0025/README.adoc

Illustrates a scenario where authentication fails for the 'pfexec pkg refresh' command after the user is prompted for their password. This indicates an issue with the provided credentials or profile access.

```shell
bob@bloody:~% pfexec pkg refresh
Authentication required for 'Software Installation' profile
Password:
Authentication failed

```

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

### Iterate Over DMA Cookies Example (C)

Source: https://github.com/illumos/ipd/blob/master/ipd/0013/README.md

Demonstrates how to use the ddi_dma_cookie_iter function to loop through all DMA cookies associated with a handle. The loop terminates when ddi_dma_cookie_iter returns NULL, indicating the end of the cookie list.

```c
const ddi_dma_cookie_t *cookie;

for (cookie = ddi_dma_cookie_iter(handle, NULL); cookie != NULL;
     cookie = ddi_dma_cookie_iter(handle, cookie)) {
        // Process the cookie
        ...
}
```