---
name: "cap_fileargs"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/cap_fileargs"
---

# cap\_fileargs(3)

library for handling files in capability mode

## NAME

**cap\_fileargs**, **fileargs\_cinit**, **fileargs\_cinitnv**, **fileargs\_init**, **fileargs\_initnv**, **fileargs\_free**, **fileargs\_lstat**, **fileargs\_open**, **fileargs\_fopen** – library for handling files in capability mode

## SYNOPSIS

library “libcap\_fileargs”

**#include \<sys/nv.h\>**

**#include \<libcasper.h\>**

**#include \<casper/cap\_fileargs.h\>**

*fileargs\_t \**\

**fileargs\_init**(*int argc*, *char \*argv\[\]*, *int flags*, *mode\_t mode*, *cap\_rights\_t \*rightsp*, *int operations*);

*fileargs\_t \**\

**fileargs\_cinit**(*cap\_channel\_t \*cas*, *int argc*, *char \*argv\[\]*, *int flags*, *mode\_t mode*, *cap\_rights\_t \*rightsp*, *int operations*);

*fileargs\_t \**\

**fileargs\_cinitnv**(*cap\_channel\_t \*cas*, *nvlist\_t \*limits*);

*fileargs\_t \**\

**fileargs\_initnv**(*nvlist\_t \*limits*);

*void*\

**fileargs\_free**(*fileargs\_t \*fa*);

*int*\

**fileargs\_lstat**(*fileargs\_t \*fa*, *const char \*path*, *struct stat \*sb*);

*int*\

**fileargs\_open**(*fileargs\_t \*fa*, *const char \*name*);

*FILE \**\

**fileargs\_fopen**(*fileargs\_t \*fa*, *const char \*name*, *const char \*mode*);

*char \**\

**fileargs\_realpath**(*fileargs\_t \*fa*, *const char \*pathname*, *char \*reserved\_path*);

## DESCRIPTION

The **cap\_fileargs** library is used to simplify Capsicumizing tools that are using file system. The idea behind the library is that we pass the remaining arguments from *argv* (with count specified by *argc*) which contains the list of files that should be opened by the program. The library creates a service that will serve those files.

The function **fileargs\_init**() creates a service to the **system.fileargs**. The *argv* contains a list of files that should be opened. The argument can be set to NULL to create no service and prohibit all files from being opened. The *argc* argument contains the number of files passed to the program. The *flags* argument specifies whether files can be opened for execution, for reading, and/or for writing. The *mode* argument specifies the permissions to use when creating new files if the O\_CREAT flag is set. For more information about the *flags* and *mode* arguments, see [open(2)](/open/2.md). The *rightsp* argument specifies the capability rights that will be applied to restrict access to the files. For more information about capability rights, see [cap\_rights\_init(3)](/cap_rights_init/3.md). The *operations* argument specifies which operations are permitted when using **system.fileargs**. The following flags can be combined to form the *operations* value:

- FA\_OPEN

  Allow **fileargs\_open**() and **fileargs\_fopen**().

- FA\_LSTAT

  Allow **fileargs\_lstat**().

- FA\_REALPATH

  Allow **fileargs\_realpath**().

The function **fileargs\_cinit**() behaves identically to **fileargs\_init**(), but requires an existing Casper connection to be passed as an argument.

The functions **fileargs\_initnv**() and **fileargs\_cinitnv**() are equivalent to **fileargs\_init**() and **fileargs\_cinit**() respectively, but take their arguments in the form of an [nvlist(9)](/nvlist/9.md) structure. See the LIMITS section for details on the expected argument types and values.

The **fileargs\_free**() function closes the connection to the **system.fileargs** service and frees all associated data structures. The function safely handles NULL arguments.

The function **fileargs\_lstat**() provides the same functionality as [lstat(2)](/lstat/2.md).

The functions **fileargs\_open**() and **fileargs\_fopen**() behave identically to [open(2)](/open/2.md) and [fopen(3)](/fopen/3.md) respectively, but retrieve their arguments from the *fileargs\_t* structure.

The function **fileargs\_realpath**() provides the same functionality as the standard C library function [realpath(3)](/realpath/3.md), resolving all symbolic links and references in a pathname.

The following functions are reentrant but require synchronization for thread safety: **fileargs\_open**(), **fileargs\_lstat**(), **fileargs\_realpath**(), **fileargs\_cinitnv**(), **fileargs\_initnv**(), and **fileargs\_fopen**(). Multiple threads can call these functions safely only if they use different *cap\_channel\_t* arguments or proper synchronization mechanisms.

## LIMITS

This section describes the required and optional arguments that must be passed to *system.fileargs* via the **fileargs\_initnv**() and **fileargs\_cinitnv**() functions using an [nvlist(9)](/nvlist/9.md) structure.

The following arguments are required:

- flags (NV\_TYPE\_NUMBER)

  Specifies access permissions for opened files.

- mode (NV\_TYPE\_NUMBER)

  Required when the O\_CREAT flag is set in *flags*. Specifies the permissions to use when creating new files.

- operations (NV\_TYPE\_NUMBER)

  Specifies which operations are allowed for *system.fileargs*. See the description of the *operations* argument in **fileargs\_init**() for possible values.

The following arguments are optional in the [nvlist(9)](/nvlist/9.md) structure:

- cap\_rights (NV\_TYPE\_BINARY)

  The *cap\_rights* argument specifies the capability rights that will be applied to restrict access to opened files.

- filenames (NV\_TYPE\_NULL)

  Multiple NV\_TYPE\_NULL elements can be provided, where each element's name represents a file path that is allowed to be opened.

## EXAMPLES

```
int ch, fd, i;
cap_rights_t rights;
fileargs_t *fa;
while ((ch = getopt(argc, argv, "h")) != -1) {
	switch (ch) {
		case 'h':
		default:
			usage();
	}
}
argc -= optind;
argv += optind;
/* Create capability to the system.fileargs service. */
fa = fileargs_init(argc, argv, O_RDONLY, 0,
    cap_rights_init(&rights, CAP_READ), FA_OPEN);
if (fa == NULL)
	err(1, "unable to open system.fileargs service");
/* Enter capability mode sandbox. */
if (cap_enter() < 0 && errno != ENOSYS)
	err(1, "unable to enter capability mode");
/* Open files. */
for (i = 0; i < argc; i++) {
	fd = fileargs_open(fa, argv[i]);
	if (fd < 0)
		err(1, "unable to open file %s", argv[i]);
	printf("File %s opened in capability mode\n", argv[i]);
	close(fd);
}
fileargs_free(fa);
```

## SEE ALSO

[cap\_enter(2)](/cap_enter/2.md), [lstat(2)](/lstat/2.md), [open(2)](/open/2.md), [cap\_rights\_init(3)](/cap_rights_init/3.md), [err(3)](/err/3.md), [fopen(3)](/fopen/3.md), [getopt(3)](/getopt/3.md), [realpath(3)](/realpath/3.md), [capsicum(4)](/capsicum/4.md), [nv(9)](/nv/9.md)

## HISTORY

The **cap\_fileargs** service first appeared in FreeBSD 10.3.

## AUTHORS

Mariusz Zaborski ⟨*oshogbo@FreeBSD.org*⟩

## BUGS

The **cap\_fileargs** service is considered experimental and should be thoroughly evaluated for risks before deploying in production environments.