Provided by: libselinux1-dev_3.3-1build2_amd64 bug

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

       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  KERNEL  STATUS  PAGE  and
       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.

KERNEL STATUS PAGE

       Linux  kernel  version  2.6.37 supports the SELinux kernel status page, enabling userspace
       applications to mmap(2) SELinux status state in  read-only  mode  to  avoid  system  calls
       during the cache hit code path.

       avc_init()  calls  selinux_status_open(3)  to  initialize  the  selinux  status  state. If
       successfully initialized, the userspace AVC  will  default  to  single-threaded  mode  and
       ignore  the  func_create_thread  and  func_stop_thread  callbacks.  All  callbacks set via
       selinux_set_callback(3) will still be honored.

       avc_has_perm(3) and selinux_check_access(3) both check for status updates through calls to
       selinux_status_updated(3)  at  the start of each permission query and take the appropriate
       action.

       Two status types are currently implemented.  setenforce events will change  the  effective
       enforcing state used within the AVC, and policyload events will result in a cache flush.

NETLINK NOTIFICATION

       In  the  event  that  the  kernel  status page is not successfully mmap(2)'ed the AVC will
       default to the netlink fallback mechanism, which opens  a  netlink  socket  for  receiving
       status  updates.   setenforce  and policyload events will have the same results as for the
       status page implementation, but all status update checks will now require a system call.

       By default, avc_open(3) does not set threading or locking callbacks. In the fallback case,
       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(), a dedicated  thread  will  be
       started  to listen on the netlink socket.  This may increase performance in the absence of
       the status page 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
       further permission checks until avc_destroy is called.

AUTHOR

       Eamon Walsh <ewalsh@tycho.nsa.gov>

SEE ALSO

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

                                           27 May 2004                                avc_init(3)