NAME | SYNOPSIS | DESCRIPTION | CALLBACKS | NETLINK NOTIFICATION | RETURN VALUE | NOTES | AUTHOR | SEE ALSO | COLOPHON

avc_init(3)               SELinux API documentation              avc_init(3)

NAME         top

       avc_init - legacy userspace SELinux AVC setup

SYNOPSIS         top

       #include <selinux/selinux.h>
       #include <selinux/avc.h>

       int avc_init(const char *msgprefix,
                    const struct avc_memory_callback *mem_callbacks,
                    const struct avc_log_callback *log_callbacks,
                    const struct avc_thread_callback *thread_callbacks,
                    const struct avc_lock_callback *lock_callbacks);

DESCRIPTION         top

       avc_init() is deprecated; please use avc_open(3) in conjunction with
       selinux_set_callback(3) in all new code.

       avc_init() initializes the userspace AVC and must be called before
       any other AVC operation can be performed.  A non-NULL msgprefix will
       be prepended to all audit messages produced by the userspace AVC.
       The default is `uavc'.  The remaining arguments, if non-NULL, specify
       callbacks to be used by the userspace AVC.

CALLBACKS         top

       The userspace AVC can be directed how to perform memory allocation,
       logging, thread creation, and locking via callback functions passed
       to avc_init().  The purpose of this functionality is to allow the
       userspace AVC to be smoothly integrated into existing userspace
       object managers.

       Use an avc_memory_callback structure to specify alternate functions
       for dynamic memory allocation.

              struct avc_memory_callback {
                  void  *(*func_malloc)(size_t size);
                  void  (*func_free)(void *ptr);
              };

       The two fields of the structure should be pointers to functions which
       behave as malloc(3) and free(3), which are used by default.

       Use an avc_log_callback structure to specify alternate functions for
       logging.

              struct avc_log_callback {
                  void  (*func_log)(const char *fmt, ...);
                  void  (*func_audit)(void *auditdata,
                                      security_class_t class,
                                      char *msgbuf, size_t msgbufsize);
              };

       The func_log callback should accept a printf(3) style format and
       arguments and log them as desired.  The default behavior prints the
       message on the standard error.  The func_audit callback should
       interpret the auditdata parameter for the given class, printing a
       human-readable interpretation to msgbuf using no more than msgbufsize
       characters.  The default behavior is to ignore auditdata.

       Use an avc_thread_callback structure to specify functions for
       starting and manipulating threads.

              struct avc_thread_callback {
                  void  *(*func_create_thread)(void (*run)(void));
                  void  (*func_stop_thread)(void *thread);
              };

       The func_create_thread callback should create a new thread and return
       a pointer which references it.  The thread should execute the run
       argument, which does not return under normal conditions.  The
       func_stop_thread callback should cancel the running thread referenced
       by thread.  By default, threading is not used; see NETLINK
       NOTIFICATION below.

       Use an avc_lock_callback structure to specify functions to create,
       obtain, and release locks for use by threads.

              struct avc_lock_callback {
                  void  *(*func_alloc_lock)(void);
                  void  (*func_get_lock)(void *lock);
                  void  (*func_release_lock)(void *lock);
                  void  (*func_free_lock)(void *lock);
              };

       The func_alloc_lock callback should create a new lock, returning a
       pointer which references it.  The func_get_lock callback should
       obtain lock, blocking if necessary.  The func_release_lock callback
       should release lock.  The func_free_lock callback should destroy
       lock, freeing any resources associated with it.  The default behavior
       is not to perform any locking.  Note that undefined behavior may
       result if threading is used without appropriate locking.

NETLINK NOTIFICATION         top

       Beginning with version 2.6.4, the Linux kernel supports SELinux
       status change notification via netlink.  Two message types are
       currently implemented, indicating changes to the enforcing mode and
       to the loaded policy in the kernel, respectively.  The userspace AVC
       listens for these messages and takes the appropriate action,
       modifying the behavior of avc_has_perm(3) to reflect the current
       enforcing mode and flushing the cache on receipt of a policy load
       notification.  Audit messages are produced when netlink notifications
       are processed.

       In the default single-threaded mode, the userspace AVC checks for new
       netlink messages at the start of each permission query.  If threading
       and locking callbacks are passed to avc_init() however, a dedicated
       thread will be started to listen on the netlink socket.  This may
       increase performance and will ensure that log messages are generated
       immediately rather than at the time of the next permission query.

RETURN VALUE         top

       Functions with a return value return zero on success.  On error, -1
       is returned and errno is set appropriately.

NOTES         top

       The msgprefix argument to avc_init() currently has a length limit of
       15 characters and will be truncated if necessary.

       If a provided func_malloc callback does not set errno appropriately
       on error, userspace AVC calls may exhibit the same behavior.

       If a netlink thread has been created and an error occurs on the
       socket (such as an access error), the thread may terminate and cause
       the userspace AVC to return EINVAL on all further permission checks
       until avc_destroy is called.

AUTHOR         top

       Eamon Walsh <ewalsh@tycho.nsa.gov>

SEE ALSO         top

       avc_open(3), selinux_set_callback(3), selinux(8)

COLOPHON         top

       This page is part of the selinux (Security-Enhanced Linux user-space
       libraries and tools) project.  Information about the project can be
       found at ⟨https://github.com/SELinuxProject/selinux/wiki⟩.  If you
       have a bug report for this manual page, see 
       ⟨https://github.com/SELinuxProject/selinux/wiki/Contributing⟩.  This
       page was obtained from the project's upstream Git repository 
       ⟨https://github.com/SELinuxProject/selinux⟩ on 2017-07-05.  If you
       discover any rendering problems in this HTML version of the page, or
       you believe there is a better or more up-to-date source for the page,
       or you have corrections or improvements to the information in this
       COLOPHON (which is not part of the original manual page), send a mail
       to man-pages@man7.org

                                 27 May 2004                     avc_init(3)

Pages that refer to this page: avc_add_callback(3)avc_cache_stats(3)avc_compute_create(3)avc_context_to_sid(3)avc_has_perm(3)selinux_set_callback(3)