xorriso  1.5.4.pl02
About: GNU xorriso creates, loads, manipulates and writes ISO 9660 filesystem images with Rock Ridge extensions. It is suitable for incremental data backup and for production of bootable ISO 9660 images. GNU xorriso is a statical compilation of the libraries libburn, libisofs, libisoburn, and libjte.
  Fossies Dox: xorriso-1.5.4.pl02.tar.gz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

aaip_0_2.h
Go to the documentation of this file.
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 
ssize_t aaip_encode(size_t num_attrs, char **names, size_t *value_lengths, char **values, size_t *result_len, unsigned char **result, int flag)
Definition: aaip_0_2.c:100
int aaip_init_aaip_state(struct aaip_state *aaip, int flag)
Definition: aaip_0_2.c:983
int aaip_set_attr_list(char *path, size_t num_attrs, char **names, size_t *value_lengths, char **values, int *errnos, int flag)
int aaip_get_attr_list(char *path, size_t *num_attrs, char ***names, size_t **value_lengths, char ***values, int flag)
Definition: aaip-os-dummy.c:74
unsigned int aaip_get_pairs_skipped(struct aaip_state *aaip, int flag)
Definition: aaip_0_2.c:1716
int aaip_add_acl_st_mode(char *acl_text, mode_t st_mode, int flag)
Definition: aaip_0_2.c:865
int aaip_submit_data(struct aaip_state *aaip, unsigned char *data, size_t num_data, size_t *ready_bytes, int flag)
Definition: aaip_0_2.c:1371
size_t aaip_count_bytes(unsigned char *data, int flag)
Definition: aaip_0_2.c:966
int aaip_get_decoded_attrs(struct aaip_state **handle, size_t *num_attrs, char ***names, size_t **value_lengths, char ***values, int flag)
Definition: aaip_0_2.c:1971
int aaip_encode_acl(char *acl_text, mode_t st_mode, size_t *result_len, unsigned char **result, int flag)
Definition: aaip_0_2.c:292
int aaip_set_acl_text(char *path, char *text, int flag)
Definition: aaip-os-dummy.c:91
int aaip_decode_pair(struct aaip_state *aaip, unsigned char *data, size_t num_data, size_t *consumed, char *name, size_t name_size, size_t *name_fill, char *value, size_t value_size, size_t *value_fill, int flag)
Definition: aaip_0_2.c:1615
size_t aaip_sizeof_aaip_state(void)
Definition: aaip_0_2.c:977
int aaip_decode_acl(unsigned char *data, size_t num_data, size_t *consumed, char *acl_text, size_t acl_text_size, size_t *acl_text_fill, int flag)
Definition: aaip_0_2.c:2103
int aaip_decode_attrs(struct aaip_state **handle, size_t memory_limit, size_t num_attr_limit, unsigned char *data, size_t num_data, size_t *consumed, int flag)
Definition: aaip_0_2.c:1785
int aaip_get_acl_text(char *path, char **text, int flag)
Definition: aaip-os-dummy.c:64
int aaip_skip_component(struct aaip_state *aaip, int flag)
Definition: aaip_0_2.c:1487
int aaip_encode_both_acl(char *a_acl_text, char *d_acl_text, mode_t st_mode, size_t *result_len, unsigned char **result, int flag)
Definition: aaip_0_2.c:618
int aaip_cleanout_st_mode(char *acl_text, mode_t *st_mode, int flag)
Definition: aaip_0_2.c:720
int aaip_fetch_data(struct aaip_state *aaip, char *result, size_t result_size, size_t *num_result, int flag)
Definition: aaip_0_2.c:1432
int aaip_local_attr_support(int flag)
Definition: aaip-os-dummy.c:53
size_t ready_bytes
Definition: aaip_0_2.c:935