.TH "matchpathcon" "3" "16 March 2005" "sds@tycho.nsa.gov" "SE Linux API documentation"

.SH "NAME"

matchpathcon \- get the default 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 ");"

.br

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

.sp

.br 

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

.br

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

.br

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

.br

.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.

.br 

.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

.br

.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.

.br

.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.

.br

.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.

.br

.sp

.SH "RETURN VALUE"

Returns 0 on success or -1 otherwise.

.SH "SEE ALSO"

.BR freecon "(3), " setfilecon "(3), " setfscreatecon "(3)"