libselinux/man/man3/matchpathcon.3

.TH "matchpathcon" "3" "16 March 2005" "sds@tycho.nsa.gov" "SELinux API documentation"
.SH "NAME"
matchpathcon \- get the default SELinux security context for the specified path from the file contexts configuration.

.SH "SYNOPSIS"
.B #include <selinux/selinux.h>
.sp
.BI "int matchpathcon_init(const char *" path ");"

.BI "int matchpathcon_fini(void);"

.BI "int matchpathcon(const char *" path ", mode_t " mode ", security_context_t *" con);
.sp

.BI "void set_matchpathcon_printf(void (*" f ")(const char *" fmt ", ...));"

.BI "void set_matchpathcon_invalidcon(int (*" f ")(const char *"path ", unsigned " lineno ", char * " context "));"

.BI "void set_matchpathcon_flags(unsigned int " flags ");"

.SH "DESCRIPTION"
.B matchpathcon_init
loads the file contexts configuration specified by
.I path
into memory for use by subsequent 
.B matchpathcon 
calls.  If
.I path
is NULL, then the active file contexts configuration is loaded by default,
i.e. the path returned by 
.B selinux_file_context_path(3).
Unless the 
.B MATCHPATHCON_BASEONLY 
flag has been set via 
.B set_matchpathcon_flags,
files with the same path prefix but a 
.B .homedirs
and
.B .local
suffix are also looked up and loaded if present.  These files provide
dynamically generated entries for user home directories and for local
customizations.

.sp
.B matchpathcon_fini
frees the memory allocated by a prior call to
.B matchpathcon_init.
This function can be used to free and reset the internal state between multiple 
.B matchpathcon_init 
calls, or to free memory when finished using 
.B matchpathcon.

.sp
.B matchpathcon 
matches the specified pathname and mode against the file contexts
configuration and sets the security context 
.I con 
to refer to the
resulting context. The caller must free the returned security context 
.I con
using freecon when finished using it.
.I mode
can be 0 to disable mode matching, but
should be provided whenever possible, as it may affect the matching.
Only the file format bits (i.e. the file type) of the 
.I mode 
are used.
If 
.B matchpathcon_init
has not already been called, then this function will call it upon
its first invocation with a NULL
.I path,
defaulting to the active file contexts configuration.
.sp

.B set_matchpathcon_printf
sets the function used by 
.B matchpathcon_init
when displaying errors about the file contexts configuration.  If not set, 
then this defaults to fprintf(stderr, fmt, ...).  This can be set to redirect
error reporting to a different destination.

.sp
.B set_matchpathcon_invalidcon
sets the function used by 
.B matchpathcon_init
when checking the validity of a context in the file contexts
configuration.  If not set, then this defaults to a test based 
on 
.B security_check_context(3),
which checks validity against the active policy on a SELinux system.
This can be set to instead perform checking based on a binary policy file,
e.g. using 
.B sepol_check_context(3),
as is done by 
.B setfiles -c.
The function is also responsible for reporting any such error, and
may include the 
.I path
and
.I lineno
in such error messages.

.sp
.B set_matchpathcon_flags
sets flags controlling the operation of 
.B matchpathcon_init
or
.B matchpathcon.
If the 
.B MATCHPATHCON_BASEONLY
flag is set, then only the base file contexts configuration file
will be processed, not any dynamically generated entries or local customizations.

.sp
.SH "RETURN VALUE"
Returns 0 on success or -1 otherwise.

.SH "SEE ALSO"
.BR selinux "(8), " freecon "(3), " setfilecon "(3), " setfscreatecon "(3)"