"Fossies" - the Fresh Open Source Software Archive

Member "xorriso-1.5.4/libisofs/aaip_0_2.h" (30 Jan 2021, 25205 Bytes) of package /linux/misc/xorriso-1.5.4.pl02.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "aaip_0_2.h" see the Fossies "Dox" file reference documentation and the last Fossies "Diffs" side-by-side code changes report: 1.5.2_vs_1.5.4.

    1 
    2 /*
    3 
    4  Arbitrary Attribute Interchange Protocol , AAIP versions 0.2 and 1.0.
    5  Implementation for encoding and decoding xattr and ACL.
    6 
    7  See http://libburnia-project.org/wiki/AAIP
    8  or  doc/susp_aaip_2_0.txt
    9 
   10  test/aaip_0_2.h - Public declarations
   11 
   12  Copyright (c) 2009 - 2016 Thomas Schmitt
   13 
   14  This file is part of the libisofs project; you can redistribute it and/or
   15  modify it under the terms of the GNU General Public License version 2
   16  or later as published by the Free Software Foundation.
   17  See COPYING file for details.
   18 
   19 */
   20 
   21 #ifndef Aaip_h_is_includeD
   22 #define Aaip_h_is_includeD yes
   23 
   24 /* For ssize_t */
   25 #include <unistd.h>
   26 
   27 
   28 /* --------------------------------- Encoder ---------------------------- */
   29 
   30 /* Convert an array of Arbitrary Attributes into a series of AAIP fields.
   31    @param num_attrs     Number of attributes
   32    @param names         Array of pointers to 0 terminated name strings
   33    @param value_lengths Array of byte lengths for each value
   34    @param values        Array of pointers to the value bytes
   35    @param result_len    Number of bytes in the resulting SUSP field string
   36    @param result        *result will point to the start of the result string.
   37                         This is malloc() memory which needs to be freed when
   38                         no longer needed 
   39    @param flag          Bitfield for control purposes
   40                         bit0= set CONTINUE bit of last AAIP field to 1
   41    @return              >= 0 is the number of SUSP fields generated,
   42                         < 0 means error
   43 */
   44 ssize_t aaip_encode(size_t num_attrs, char **names,
   45                     size_t *value_lengths, char **values, 
   46                     size_t *result_len, unsigned char **result, int flag);
   47 
   48 
   49 /* ------ ACL representation ------ */
   50 
   51 /* Convert an ACL from long text form into the value of an Arbitrary
   52    Attribute. According to AAIP this value is to be stored together with
   53    an empty name.
   54    @param acl_text      The ACL in long text form
   55    @param st_mode       The stat(2) permission bits to be used with flag bit3
   56    @param result_len    Number of bytes in the resulting value
   57    @param result        *result will point to the start of the result string.
   58                         This is malloc() memory which needs to be freed when
   59                         no longer needed
   60    @param flag          Bitfield for control purposes
   61                         bit0= count only
   62                         bit1= use numeric qualifiers rather than names
   63                         bit2= this is a default ACL, prepend SWITCH_MARK
   64                         bit3= check for completeness of list and eventually
   65                               fill up with entries deduced from st_mode
   66    @return              >0 means ok
   67                         <=0 means error
   68                         -1= out of memory
   69                         -2= program error with prediction of result size
   70                         -3= error with conversion of name to uid or gid
   71      ISO_AAIP_ACL_MULT_OBJ= multiple entries of user::, group::, other::
   72 */
   73 int aaip_encode_acl(char *acl_text, mode_t st_mode,
   74                     size_t *result_len, unsigned char **result, int flag);
   75 
   76 
   77 /* Convert an "access" and "default" ACL from long text form into the value
   78    of an Arbitrary Attribute. According to AAIP this value is to be stored
   79    together with an empty name.
   80    @param a_acl_text    The "access" ACL in long text form.
   81                         Submit NULL if there is no such ACL to be encoded.
   82    @param d_acl_text    The "default" ACL in long text form.
   83                         Submit NULL if there is no such ACL to be encoded.
   84    @param st_mode       The stat(2) permission bits to be used with flag bit3
   85    @param result_len    Number of bytes in the resulting value
   86    @param result        *result will point to the start of the result string.
   87                         This is malloc() memory which needs to be freed when
   88                         no longer needed
   89    @param flag          Bitfield for control purposes
   90                         bit0= count only
   91                         bit1= use numeric qualifiers rather than names
   92                         bit3= check for completeness of list and eventually
   93                               fill up with entries deduced from st_mode
   94    @return              >0 means ok
   95                         <=0 means error, see aaip_encode_acl
   96 */
   97 int aaip_encode_both_acl(char *a_acl_text, char *d_acl_text, mode_t st_mode,
   98                          size_t *result_len, unsigned char **result, int flag);
   99 
  100 
  101 /* Analyze occurrence of ACL tag types in long text form. If not disabled by
  102    parameter flag remove the entries of type "user::" , "group::" , "other::" ,
  103    or "other:" from an ACL in long text form if they match the bits in st_mode
  104    as described by man 2 stat and man 5 acl.
  105    @param acl_text   The text to be analyzed and eventually shortened.
  106    @param st_mode    The component of struct stat which tells permission
  107                      bits and eventually shall take equivalent bits as read
  108                      from the ACL. The caller should submit a pointer
  109                      to the st_mode variable which holds permissions as
  110                      indicated by stat(2) resp. ECMA-119 and RRIP data.
  111    @param flag       bit0= do not remove entries, only determine return value
  112                      bit1= like bit0 but return immediately if a non-st_mode
  113                            ACL entry is found
  114                      bit2= update *st_mode by acl_text
  115                            ("user::" -> S_IRWXU, "mask::"|"group::" -> S_IRWXG,
  116                             "other::" -> S_IRWXO)
  117                      bit3= update acl_text by *st_mode (same mapping as bit 2 
  118                            but with reversed transfer direction)
  119                      bit4= map "group::" <-> S_IRWXG in any case.
  120                            I.e. ignore "mask::".
  121    @return           <0  failure
  122                      >=0 tells in its bits which tag types were found.
  123                          The first three tell which types deviate from the
  124                          corresponding st_mode settings:
  125                          bit0= "other::" overrides S_IRWXO
  126                          bit1= "group::" overrides S_IRWXG (no "mask::" found)
  127                          bit2= "user::"  overrides S_IRWXU       
  128                          The second three tell which types comply with st_mode:
  129                          bit3= "other::" matches S_IRWXO
  130                          bit4= "group::" matches S_IRWXG (no "mask::" found)
  131                          bit5= "user::"  matches S_IRWXU       
  132                          Given the nature of ACLs nearly all combinations are
  133                          possible although some would come from invalid ACLs.
  134                          bit6= other ACL tag types are present. Particularly:
  135                                bit7= "user:...:" is present
  136                                bit8= "group:...:" is present
  137                                bit9= "mask::" is present
  138                          bit10= "group::" found and "mask::" exists
  139                          
  140 */
  141 int aaip_cleanout_st_mode(char *acl_text, mode_t *st_mode, int flag);
  142 
  143 
  144 /* Append entries of type "user::" , "group::" , "other::" representing the
  145    permission bits in st_mode if those tag types are not present in the ACL
  146    text. Append "mask::" if missing although "user:...:" or "group:...:"
  147    is present. Eventually set it to S_IRWXG bits of st_mode.
  148    @param acl_text   The text to be made longer. It must offer 43 bytes more
  149                      storage space than its length when it is submitted.
  150    @param st_mode    The component of struct stat which shall provide the
  151                      permission information.
  152    @param flag       Unused yet. Submit 0.
  153    @return           <0 failure
  154 */
  155 int aaip_add_acl_st_mode(char *acl_text, mode_t st_mode, int flag);
  156 
  157 
  158 /* ------ OS interface ------ */
  159 
  160 /* See also API iso_local_attr_support().
  161    @param flag
  162         Bitfield for control purposes
  163              bit0= inquire availability of ACL
  164              bit1= inquire availability of xattr
  165              bit2 - bit7= Reserved for future types.
  166                           It is permissibile to set them to 1 already now.
  167              bit8 and higher: reserved, submit 0
  168    @return
  169         Bitfield corresponding to flag. If bits are set, th
  170              bit0= ACL adapter is enabled
  171              bit1= xattr adapter is enabled
  172              bit2 - bit7= Reserved for future types.
  173              bit8 and higher: reserved, do not interpret these
  174 */
  175 int aaip_local_attr_support(int flag);
  176 
  177 
  178 /* Obtain the ACL of the given file in long text form.
  179    @param path          Path to the file
  180    @param text          Will hold the result. This is a managed object which
  181                         finally has to be freed by a call to this function
  182                         with bit15 of flag.
  183    @param flag          Bitfield for control purposes
  184                         bit0=  obtain default ACL rather than access ACL
  185                         bit4=  set *text = NULL and return 2
  186                                if the ACL matches st_mode permissions.
  187                         bit15= free text and return 1
  188    @return               1 ok
  189                          2 only st_mode permissions exist and bit 4 is set
  190                          0 ACL support not enabled at compile time
  191                         -1 failure of system ACL service (see errno)
  192 */
  193 int aaip_get_acl_text(char *path, char **text, int flag);
  194 
  195 
  196 /* Obtain the Extended Attributes and/or the ACLs of the given file in a form
  197    that is ready for aaip_encode(). The returned data objects finally have
  198    to be freed by a call with flag bit 15.
  199    @param path          Path to the file
  200    @param num_attrs     Will return the number of name-value pairs
  201    @param names         Will return an array of pointers to 0-terminated names
  202    @param value_lengths Will return an array with the lengths of values
  203    @param values        Will return an array of pointers to 8-bit values
  204    @param flag          Bitfield for control purposes
  205                         bit0=  obtain ACLs (access and eventually default) via
  206                                system ACL API and encode 
  207                         bit1=  use numeric ACL qualifiers rather than names
  208                         bit2=  do not obtain attributes other than ACLs
  209                         bit3=  do not ignore eventual non-user attributes.
  210                                I.e. those with a name which does not begin
  211                                by "user."
  212                         bit4=  do not return trivial ACL that matches st_mode
  213                         bit15= free memory of names, value_lengths, values
  214    @return              >0  ok
  215                         <=0 error
  216 */
  217 int aaip_get_attr_list(char *path, size_t *num_attrs, char ***names,
  218                        size_t **value_lengths, char ***values, int flag);
  219 
  220 
  221 /* --------------------------------- Decoder ---------------------------- */
  222 
  223 /*
  224    The AAIP decoder offers several levels of abstraction of which the
  225    lower two avoid the use of dynamic memory. It provides a stateful decoding
  226    context with a small buffer which delivers results to caller provided
  227    memory locations.
  228 
  229    The lowest level is the stream-like Component Level Interface. It allows
  230    to decode very many very long attributes.
  231  
  232    Next is the Pair Level Interface which delivers to fixly sized storage for
  233    name and value. It allows to decode very many attributes. 
  234 
  235    The List Level Interface uses dynamic memory allocation to provide arrays
  236    of names, values and value lengths. It is intended for moderately sized
  237    attribute lists but may also be used as alternative to Pair Level.
  238 */
  239 
  240 /* Operations on complete AAIP field strings which need no decoder context.
  241    These function expect to get submitted a complete chain of AAIP fields.
  242 */
  243 
  244 /* Determine the size of the AAIP string by interpreting the SUSP structure.
  245    @param data          An arbitrary number of bytes beginning with the
  246                         complete chain of AAIP fields. Trailing trash is
  247                         ignored.
  248    @param flag          Unused yet. Submit 0.
  249    @return              The number of bytes of the AAIP field chain.
  250 */
  251 size_t aaip_count_bytes(unsigned char *data, int flag);
  252 
  253 
  254 /* The AAIP decoder context.
  255 */
  256 struct aaip_state;
  257 
  258 
  259 /* Obtain the size in bytes of an aaip_state object.
  260 */
  261 size_t aaip_sizeof_aaip_state(void);
  262 
  263 
  264 /* Initialize a AAIP decoder context.
  265    This has to be done before the first AAIP field of a node is processed.
  266    The caller has to provide the storage of the struct aaip_state.
  267    @param aaip          The AAIP decoder context to be initialized
  268    @param flag          Bitfield for control purposes
  269                         submit 0
  270    @return <=0 error , >0 ok
  271 */
  272 int aaip_init_aaip_state(struct aaip_state *aaip, int flag);
  273 
  274 
  275 /* -------------------------  Component Level Interface  ------------------- */
  276 /* 
  277    Provides support for unlimited component size but demands the caller
  278    to have a growing storage facility resp. to do own oversize handling.
  279 
  280    This interface expects moderatly sized input pieces and will hand out
  281    moderately sized result pieces. The number of transactions is virtually
  282    unlimited. 
  283 */
  284 
  285 /* Submit small data chunk for decoding.
  286    The return value will tell whether data are pending for being fetched.
  287    @param aaip          The AAIP decoder context
  288    @param data          Not more than 2048 bytes input for the decoder
  289    @param num_data      Number of bytes in data
  290                         0 inquires the buffer status avoiding replies <= 0
  291    @param ready_bytes   Number of decoded bytes ready for delivery
  292    @param flag          Bitfield for control purposes
  293    @return             -1= non-AAIP field detected
  294                            *ready_bytes gives number of consumed bytes in data
  295                         0= cannot accept data because buffer full
  296                         1= no component record complete, submit more data
  297                         2= component record complete, may be delivered
  298                         3= component complete, may be delivered
  299                         4= no component available, no more data expected, done
  300 */
  301 int aaip_submit_data(struct aaip_state *aaip,
  302                      unsigned char *data, size_t num_data,
  303                      size_t *ready_bytes, int flag);
  304 
  305 
  306 /* Fetch the available part of current component.
  307    The return value will tell whether it belongs to name or to value and
  308    whether that name or value is completed now.
  309    @param aaip          The AAIP decoder context
  310    @param result        Has to point to storage for the component data
  311    @param result_size   Gives the amount of provided result storage
  312    @param num_result    Will tell the number of fetched result bytes
  313    @param flag          Bitfield for control purposes
  314                         bit0= discard data rather than copying to result
  315    @return -2 = insufficient result_size
  316            -1 = no data ready for delivery
  317             0 = result holds the final part of a name
  318             1 = result holds an intermediate part of a name
  319             2 = result holds the final part of a value
  320             3 = result holds an intermediate part of a value
  321 */
  322 int aaip_fetch_data(struct aaip_state *aaip,
  323                     char *result, size_t result_size, size_t *num_result,
  324                     int flag);
  325 
  326 
  327 /* Skip the current component and eventually the following value component.
  328    This has to be called if fetching of a component shall be aborted
  329    but the next component resp. pair shall be fetchable again.
  330    aaip_submit_data() will not indicate readiness for fetching until all
  331    bytes of the skipped components are submitted. Those bytes get discarded.
  332    @param aaip          The AAIP decoder context
  333    @param flag          Bitfield for control purposes
  334                         bit0= do not skip value if current component is name
  335    @return              <=0 error , 1= now in skip state, 2= not in skip state
  336 */
  337 int aaip_skip_component(struct aaip_state *aaip, int flag);
  338 
  339 
  340 /* -------------------------  Pair Level Interface  ------------------------ */
  341 /*
  342    Provides support for names and values of limited size. The limits are
  343    given by the caller who has to provide the storage for name and value.
  344 
  345    This interface expects moderatly sized input pieces.
  346    The number of input transcations is virtually unlimited.
  347    The number of pair transactions after aaip_init() should be limited
  348    to 4 billion.
  349 */
  350 
  351 
  352 /* Accept raw input data and collect a pair of name and value.
  353    The return value will indicate whether the pair is complete, whether more
  354    pairs are complete or whether more data are desired. No input data will be
  355    accepted as long as complete pairs are pending. The end of the attribute
  356    list will be indicated.
  357    @param aaip          The AAIP decoder context
  358    @param data          The raw data to decode
  359    @param num_data      Number of data bytes provided
  360    @param consumed      Returns the number of consumed data bytes
  361    @param name          Buffer to build the name string
  362    @param name_size     Maximum number of bytes in name
  363    @param name_fill     Holds the current buffer fill of name
  364    @param value         Buffer to build the value string
  365    @param value_size    Maximum number of bytes in value
  366    @param value_fill    Holds the current buffer fill of value
  367    @param flag          Bitfield for control purposes - submit 0 for now
  368    @return <0 error
  369             0 data not accepted, first fetch pending pairs with num_data == 0
  370             1 name and value are not valid yet, submit more data
  371             2 name and value are valid, submit more data
  372             3 name and value are valid, pairs pending, fetch with num_data == 0
  373             4 name and value are valid, no more data expected
  374             5 name and value are not valid, no more data expected
  375 
  376 */
  377 int aaip_decode_pair(struct aaip_state *aaip,
  378                      unsigned char *data, size_t num_data, size_t *consumed,
  379                      char *name, size_t name_size, size_t *name_fill,
  380                      char *value, size_t value_size, size_t *value_fill,
  381                      int flag);
  382 
  383 
  384 /* Inquire the number of pairs which were skipped because being oversized.
  385    @param aaip          The AAIP decoder context
  386    @param flag          Bitfield for control purposes - submit 0 for now
  387    @return The number of pairs skipped since aaip_init()
  388 */
  389 unsigned int aaip_get_pairs_skipped(struct aaip_state *aaip, int flag);
  390 
  391 
  392 /* -------------------------  List Level Interface  ------------------------ */
  393 /*
  394    Provides support for names and values of limited size. The limits are
  395    given for total memory consumption and for number of attributes.
  396 
  397    Iterated decoding is supported as long as no single attribute exceeds
  398    the memory limit.
  399 */
  400 
  401 /* Accept raw input data and collect arrays of name pointers, value lengths
  402    and value pointers. A handle object will emerge which finally has to be
  403    be freed by a call with bit 15.
  404    @param handle        The decoding context.
  405                         It will be created by this call with flag bit 0 or if
  406                         *handle == NULL. This handle has to be the same as long
  407                         as decoding goes on and finally has to be freed by a
  408                         call with bit15.
  409    @param memory_limit  Maximum number of bytes to allocate
  410    @param num_attr_limit  Maximum number of name-value pairs to allocate
  411    @param data          The raw data to decode
  412    @param num_data      Number of data bytes provided
  413    @param consumed      Returns the number of consumed data bytes
  414    @param flag          Bitfield for control purposes
  415                         bit0=  this is the first call for a file object
  416                         bit15= end decoding :
  417                                Free handle and its intermediate list memory.
  418    @return <=0 error
  419              1 not complete yet, submit more data
  420              2 arrays are complete, call aaip_get_decoded_attrs()
  421              3 limit exceeded, not complete yet, call with bit15 and give up
  422              4 limit exceeded, call aaip_get_decoded_attrs() and try again
  423 */
  424 int aaip_decode_attrs(struct aaip_state **handle,
  425                       size_t memory_limit, size_t num_attr_limit,
  426                       unsigned char *data, size_t num_data, size_t *consumed, 
  427                       int flag);
  428 
  429 
  430 /* Obtain the resulting attributes when aaip_decode_attrs() indicates to
  431    be done or to have the maximum possible amount of result ready.
  432    The returned data objects get detached from handle making it ready for
  433    the next round of decoding with possibly a different input source. The
  434    returned data objects finally have to be freed by a call with flag bit 15.
  435    @param handle        The decoding context created by aaip_decode_attrs()
  436    @param num_attrs     Will return the number of name-value pairs
  437    @param names         Will return an array of pointers to 0-terminated names
  438    @param value_lengths Will return an array with the lengths of values
  439    @param values        Will return an array of pointers to 8-bit values
  440    @param flag          Bitfield for control purposes
  441                         bit15= free memory of names, value_lengths, values
  442 */
  443 int aaip_get_decoded_attrs(struct aaip_state **handle, size_t *num_attrs,
  444                          char ***names, size_t **value_lengths, char ***values,
  445                          int flag);
  446 
  447 
  448 /* ------ ACL representation ------ */
  449 
  450 /* Convert an AAIP ACL attribute value into the long text form of ACL.
  451    @param data          The raw data to decode
  452    @param num_data      Number of data bytes provided
  453    @param consumed      Returns the number of consumed data bytes
  454    @param acl_text      Will be filled with ACL long text form
  455    @param acl_text_size Maximum number of bytes to be written to acl_text
  456    @param acl_text_fill Will return the number of bytes in acl_text
  457    @param flag          Bitfield for control purposes
  458                         bit0= count only, do not really produce bytes:
  459                                acl_text will not be touched,
  460                                acl_text_size will be ignored,
  461                                *acl_text_fill will return the counted number
  462                         bit1= expected is a default ACL (see return value 2)
  463    @return              1 success
  464                         2 success, begin of default/access ACL encountered,
  465                           submit data + *consumed for access/default ACL
  466                        -1 error with reading of qualifier
  467                        -2 error with writing of ACL text line
  468                        -3 version mismatch
  469                        -4 unknown tag type encountered
  470 */
  471 int aaip_decode_acl(unsigned char *data, size_t num_data, size_t *consumed,
  472                     char *acl_text, size_t acl_text_size,
  473                     size_t *acl_text_fill, int flag);
  474 
  475 
  476 /* ------ OS interface ------ */
  477 
  478 /* Set the ACL of the given file to a given list in long text form.
  479    @param path          Path to the file
  480    @param text          The input text (0 terminated, ACL long text form)
  481    @param flag          Bitfield for control purposes
  482                         bit0=  set default ACL rather than access ACL
  483    @return              >0 ok
  484                          0 ACL support not enabled at compile time
  485                         -1 failure of system ACL service (see errno)
  486 */
  487 int aaip_set_acl_text(char *path, char *text, int flag);
  488 
  489 
  490 /* Bring the given attributes and/or ACLs into effect with the given file.
  491    @param path          Path to the file
  492    @param num_attrs     Number of attributes
  493    @param names         Array of pointers to 0 terminated name strings
  494    @param value_lengths Array of byte lengths for each attribute payload
  495    @param values        Array of pointers to the attribute payload bytes
  496    @param flag          Bitfield for control purposes
  497                         bit0= decode and set ACLs
  498                         bit1= first clear all existing attributes of the file
  499                         bit2= do not set attributes other than ACLs
  500                         bit3= do not ignore eventual non-user attributes.
  501                               I.e. those with a name which does not begin
  502                               by "user."
  503    @return              1 success
  504                        -1 error memory allocation
  505                        -2 error with decoding of ACL
  506                        -3 error with setting ACL
  507                        -4 error with setting attribute
  508                        -5 error with deleting attributes
  509                        -6 support of xattr not enabled at compile time
  510                        -7 support of ACL not enabled at compile time
  511                        -8 unsupported xattr namespace
  512     ISO_AAIP_ACL_MULT_OBJ multiple entries of user::, group::, other::
  513 */
  514 int aaip_set_attr_list(char *path, size_t num_attrs, char **names,
  515                        size_t *value_lengths, char **values,
  516                        int *errnos, int flag);
  517 
  518 #endif /* ! Aaip_h_is_includeD */
  519