---
name: "au_mask"
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/au_mask"
---

# au\_mask(3)

convert between string and numeric values of audit masks

## NAME

**au\_preselect**, **getauditflagsbin**, **getauditflagschar** – convert between string and numeric values of audit masks

## LIBRARY

library “libbsm”

## SYNOPSIS

**#include \<bsm/libbsm.h\>**

*int*\

**au\_preselect**(*au\_event\_t event*, *au\_mask\_t \*mask\_p*, *int sorf*, *int flag*);

*int*\

**getauditflagsbin**(*char \*auditstr*, *au\_mask\_t \*masks*);

*int*\

**getauditflagschar**(*char \*auditstr*, *au\_mask\_t \*masks*, *int verbose*);

## DESCRIPTION

These interfaces support processing of an audit mask represented by type *au\_mask\_t*, including conversion between numeric and text formats, and computing whether or not an event is matched by a mask.

The **au\_preselect**() function calculates whether or not the audit event passed via *event* is matched by the audit mask passed via *mask\_p*. The *sorf* argument indicates whether or not to consider the event as a success, if the AU\_PRS\_SUCCESS flag is set, or failure, if the AU\_PRS\_FAILURE flag is set. The *flag* argument accepts additional arguments influencing the behavior of **au\_preselect**(), including AU\_PRS\_REREAD, which causes the event to be re-looked up rather than read from the cache, or AU\_PRS\_USECACHE which forces use of the cache.

The **getauditflagsbin**() function converts a string representation of an audit mask passed via a character string pointed to by *auditstr*, returning the resulting mask, if valid, via *\*masks*.

The **getauditflagschar**() function converts the audit event mask passed via *\*masks* and converts it to a character string in a buffer pointed to by *auditstr*. See the BUGS section for more information on how to provide a buffer of sufficient size. If the *verbose* flag is set, the class description string retrieved from [audit\_class(5)](/audit_class/5.md) will be used; otherwise, the two-character class name.

## IMPLEMENTATION NOTES

The **au\_preselect**() function makes implicit use of various audit database routines, and may influence the behavior of simultaneous or interleaved processing of those databases by other code.

## RETURN VALUES

The **au\_preselect**() function returns 0 on success, or returns -1 if there is a failure looking up the event type or other database access, in which case *errno* will be set to indicate the error. It returns 1 if the event is matched; 0 if not.

The **getauditflagsbin()** and **getauditflagschar()** functions return the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

## SEE ALSO

[libbsm(3)](/libbsm/3.md), [audit\_class(5)](/audit_class/5.md)

## HISTORY

The OpenBSM implementation was created by McAfee Research, the security division of McAfee Inc., under contract to Apple Computer, Inc., in 2004. It was subsequently adopted by the TrustedBSD Project as the foundation for the OpenBSM distribution.

## AUTHORS

This software was created by Robert Watson, Wayne Salamon, and Suresh Krishnaswamy for McAfee Research, the security research division of McAfee, Inc., under contract to Apple Computer, Inc.

The Basic Security Module (BSM) interface to audit records and audit event stream format were defined by Sun Microsystems.

## BUGS

The *errno* variable may not always be properly set in the event of an error.

The **getauditflagschar**() function does not provide a way to indicate how long the character buffer is, in order to detect overflow. As a result, the caller must always provide a buffer of sufficient length for any possible mask, which may be calculated as three times the number of non-zero bits in the mask argument in the event non-verbose class names are used, and is not trivially predictable for verbose class names. This API should be replaced with a more robust one.