explain_acl_to_text(3)                                  explain_acl_to_text(3)



NNAAMMEE
       explain_acl_to_text - explain _a_c_l___t_o___t_e_x_t(3) errors

SSYYNNOOPPSSIISS
       #include <libexplain/acl_to_text.h>
       const char *explain_acl_to_text(acl_t acl, ssize_t *len_p);
       const char *explain_errno_acl_to_text(int errnum, acl_t acl, ssize_t
       *len_p);
       void explain_message_acl_to_text(char *message, int message_size, acl_t
       acl, ssize_t *len_p);
       void explain_message_errno_acl_to_text(char *message, int message_size,
       int errnum, acl_t acl, ssize_t *len_p);

DDEESSCCRRIIPPTTIIOONN
       These functions may be used to obtain explanations for errors  returned
       by the _a_c_l___t_o___t_e_x_t(3) system call.

   eexxppllaaiinn__aaccll__ttoo__tteexxtt
       const char *explain_acl_to_text(acl_t acl, ssize_t *len_p);

       The eexxppllaaiinn__aaccll__ttoo__tteexxtt function is used to obtain an explanation of an
       error returned by the _a_c_l___t_o___t_e_x_t(3) system call. The least the message
       will  contain  is  the value of strerror(errno), but usually it will do
       much better, and indicate the underlying cause in more detail.

       The _e_r_r_n_o global variable will be used to obtain the error value to  be
       decoded.

       _a_c_l     The  original acl, exactly as passed to the _a_c_l___t_o___t_e_x_t(3) sys-
               tem call.

       _l_e_n___p   The original len_p, exactly as  passed  to  the  _a_c_l___t_o___t_e_x_t(3)
               system call.

       Returns:
               The message explaining the error. This message buffer is shared
               by all libexplain functions which do not  supply  a  buffer  in
               their argument list.  This will be overwritten by the next call
               to any libexplain function which shares this buffer,  including
               other threads.

       NNoottee:: This function is nnoott thread safe, because it shares a return buf-
       fer across all threads, and many other functions in this library.

       EExxaammppllee:: This function is intended to be used in a fashion  similar  to
       the following example:
              char *result = acl_to_text(acl, len_p);
              if (!result)
              {
                  fprintf(stderr, "%s\n", explain_acl_to_text(acl, len_p));
                  exit(EXIT_FAILURE);
              }

       The   above   code   example   is   available   pre-packaged   as   the
       _e_x_p_l_a_i_n___a_c_l___t_o___t_e_x_t___o_r___d_i_e(3) function.

   eexxppllaaiinn__eerrrrnnoo__aaccll__ttoo__tteexxtt
       const char *explain_errno_acl_to_text(int errnum, acl_t acl, ssize_t
       *len_p);

       The eexxppllaaiinn__eerrrrnnoo__aaccll__ttoo__tteexxtt function is used to obtain an explanation
       of an error returned by the _a_c_l___t_o___t_e_x_t(3) system call.  The least  the
       message  will  contain  is the value of strerror(errno), but usually it
       will do much better, and indicate the underlying cause in more detail.

       _e_r_r_n_u_m  The error value to be decoded, usually obtained from the  _e_r_r_n_o
               global  variable  just  before this function is called. This is
               necessary if you need to call aannyy code between the system  call
               to  be explained and this function, because many libc functions
               will alter the value of _e_r_r_n_o.

       _a_c_l     The original acl, exactly as passed to the _a_c_l___t_o___t_e_x_t(3)  sys-
               tem call.

       _l_e_n___p   The  original  len_p,  exactly  as passed to the _a_c_l___t_o___t_e_x_t(3)
               system call.

       Returns:
               The message explaining the error. This message buffer is shared
               by  all  libexplain  functions  which do not supply a buffer in
               their argument list.  This will be overwritten by the next call
               to  any libexplain function which shares this buffer, including
               other threads.

       NNoottee:: This function is nnoott thread safe, because it shares a return buf-
       fer across all threads, and many other functions in this library.

       EExxaammppllee::  This  function is intended to be used in a fashion similar to
       the following example:
              char *result = acl_to_text(acl, len_p);
              if (!result)
              {
                  int err = errno;
                  fprintf(stderr, "%s\n", explain_errno_acl_to_text(err, acl,
                  len_p));
                  exit(EXIT_FAILURE);
              }

       The   above   code   example   is   available   pre-packaged   as   the
       _e_x_p_l_a_i_n___a_c_l___t_o___t_e_x_t___o_r___d_i_e(3) function.

   eexxppllaaiinn__mmeessssaaggee__aaccll__ttoo__tteexxtt
       void explain_message_acl_to_text(char *message, int message_size, acl_t
       acl, ssize_t *len_p);

       The  eexxppllaaiinn__mmeessssaaggee__aaccll__ttoo__tteexxtt function is used to obtain an explana-
       tion of an error returned by the _a_c_l___t_o___t_e_x_t(3) system call.  The least
       the  message  will contain is the value of strerror(errno), but usually
       it will do much better, and  indicate  the  underlying  cause  in  more
       detail.

       The  _e_r_r_n_o global variable will be used to obtain the error value to be
       decoded.

       _m_e_s_s_a_g_e The location in which to store the returned message. If a suit-
               able message return buffer is supplied, this function is thread
               safe.

       _m_e_s_s_a_g_e___s_i_z_e
               The size in bytes  of  the  location  in  which  to  store  the
               returned message.

       _a_c_l     The  original acl, exactly as passed to the _a_c_l___t_o___t_e_x_t(3) sys-
               tem call.

       _l_e_n___p   The original len_p, exactly as  passed  to  the  _a_c_l___t_o___t_e_x_t(3)
               system call.

       EExxaammppllee::  This  function is intended to be used in a fashion similar to
       the following example:
              char *result = acl_to_text(acl, len_p);
              if (!result)
              {
                  char message[3000];
                  explain_message_acl_to_text(message, sizeof(message), acl,
                  len_p);
                  fprintf(stderr, "%s\n", message);
                  exit(EXIT_FAILURE);
              }

       The   above   code   example   is   available   pre-packaged   as   the
       _e_x_p_l_a_i_n___a_c_l___t_o___t_e_x_t___o_r___d_i_e(3) function.

   eexxppllaaiinn__mmeessssaaggee__eerrrrnnoo__aaccll__ttoo__tteexxtt
       void explain_message_errno_acl_to_text(char *message, int message_size,
       int errnum, acl_t acl, ssize_t *len_p);

       The  eexxppllaaiinn__mmeessssaaggee__eerrrrnnoo__aaccll__ttoo__tteexxtt  function  is  used to obtain an
       explanation of an error returned by  the  _a_c_l___t_o___t_e_x_t(3)  system  call.
       The least the message will contain is the value of strerror(errno), but
       usually it will do much better, and indicate the  underlying  cause  in
       more detail.

       _m_e_s_s_a_g_e The location in which to store the returned message. If a suit-
               able message return buffer is supplied, this function is thread
               safe.

       _m_e_s_s_a_g_e___s_i_z_e
               The  size  in  bytes  of  the  location  in  which to store the
               returned message.

       _e_r_r_n_u_m  The error value to be decoded, usually obtained from the  _e_r_r_n_o
               global  variable  just  before this function is called. This is
               necessary if you need to call aannyy code between the system  call
               to  be explained and this function, because many libc functions
               will alter the value of _e_r_r_n_o.

       _a_c_l     The original acl, exactly as passed to the _a_c_l___t_o___t_e_x_t(3)  sys-
               tem call.

       _l_e_n___p   The  original  len_p,  exactly  as passed to the _a_c_l___t_o___t_e_x_t(3)
               system call.

       EExxaammppllee:: This function is intended to be used in a fashion  similar  to
       the following example:
              char *result = acl_to_text(acl, len_p);
              if (!result)
              {
                  int err = errno;
                  char message[3000];
                  explain_message_errno_acl_to_text(message, sizeof(message),
                  err, acl, len_p);
                  fprintf(stderr, "%s\n", message);
                  exit(EXIT_FAILURE);
              }

       The   above   code   example   is   available   pre-packaged   as   the
       _e_x_p_l_a_i_n___a_c_l___t_o___t_e_x_t___o_r___d_i_e(3) function.

SSEEEE AALLSSOO
       _a_c_l___t_o___t_e_x_t(3)
               convert an ACL to text

       _e_x_p_l_a_i_n___a_c_l___t_o___t_e_x_t___o_r___d_i_e(3)
               convert an ACL to text and report errors

CCOOPPYYRRIIGGHHTT
       libexplain version 1.4
       Copyright (C) 2013 Peter Miller



                                                        explain_acl_to_text(3)
