avc_init(3)                         SELinux API documentation                         avc_init(3)



NAME
       avc_init - legacy userspace SELinux AVC setup

SYNOPSIS
       #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
       avc_init()  is  deprecated;  please  use avc_open(3) in conjunction with selinux_set_call‐
       back(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, spec‐
       ify callbacks to be used by the userspace AVC.

CALLBACKS
       The  userspace  AVC can be directed how to perform memory allocation, logging, thread cre‐
       ation, and locking via callback functions passed to avc_init().  The purpose of this func‐
       tionality  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 ref‐
       erences it.  The thread should execute the run argument, which does not return under  nor‐
       mal 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 refer‐
       ences 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
       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
       Functions with a return value return zero on success.  On error, -1 is returned and  errno
       is set appropriately.

NOTES
       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  fur‐
       ther permission checks until avc_destroy is called.

AUTHOR
       Eamon Walsh <ewalsh AT tycho.gov>

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



                                           27 May 2004                                avc_init(3)