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)  

node.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2007 Vreixo Formoso
3  * Copyright (c) 2009 - 2020 Thomas Schmitt
4  *
5  * This file is part of the libisofs project; you can redistribute it and/or
6  * modify it under the terms of the GNU General Public License version 2
7  * or later as published by the Free Software Foundation.
8  * See COPYING file for details.
9  */
10 #ifndef LIBISO_NODE_H_
11 #define LIBISO_NODE_H_
12 
13 /*
14  * Definitions for the public iso tree
15  */
16 
17 #include "libisofs.h"
18 #include "stream.h"
19 
20 #include <sys/types.h>
21 #include <sys/stat.h>
22 #include <unistd.h>
23 
24 #ifdef HAVE_STDINT_H
25 #include <stdint.h>
26 #else
27 #ifdef HAVE_INTTYPES_H
28 #include <inttypes.h>
29 #endif
30 #endif
31 
32 
33 /* Maximum length of a leaf name in the libisofs node tree. This is currently
34  restricted by the implemented maximum length of a Rock Ridge name.
35  This might later become larger and may then be limited to smaller values.
36 
37  Rock Ridge specs do not impose an explicit limit on name length.
38  But 255 is also specified by
39  http://pubs.opengroup.org/onlinepubs/009695399/basedefs/limits.h.html
40  which says
41  NAME_MAX >= _XOPEN_NAME_MAX = 255
42 */
43 #define LIBISOFS_NODE_NAME_MAX 255
44 
45 
46 /* Maximum length of a path in the libisofs node tree.
47  Rock Ridge specs do not impose an explicit limit on path length.
48 
49  http://pubs.opengroup.org/onlinepubs/009695399/basedefs/limits.h.html
50  says
51  PATH_MAX >= _XOPEN_PATH_MAX = 1024
52 */
53 #define LIBISOFS_NODE_PATH_MAX 1024
54 
55 
56 /**
57  * The extended information is a way to attach additional information to each
58  * IsoNode. External applications may want to use this extension system to
59  * store application specific information related to each node. On the other
60  * side, libisofs may make use of this struct to attach information to nodes in
61  * some particular, uncommon, cases, without incrementing the size of the
62  * IsoNode struct.
63  *
64  * It is implemented like a chained list.
65  */
66 typedef struct iso_extended_info IsoExtendedInfo;
67 
69  /**
70  * Next struct in the chain. NULL if it is the last item
71  */
73 
74  /**
75  * Function to handle this particular extended information. The function
76  * pointer acts as an identifier for the type of the information. Structs
77  * with same information type must use the same function.
78  *
79  * @param data
80  * Attached data
81  * @param flag
82  * What to do with the data. At this time the following values are
83  * defined:
84  * -> 1 the data must be freed
85  * @return
86  * 1
87  */
89 
90  /**
91  * Pointer to information specific data.
92  */
93  void *data;
94 };
95 
96 /**
97  *
98  */
99 struct Iso_Node
100 {
101  /*
102  * Initialized to 1, originally owned by user, until added to another node.
103  * Then it is owned by the parent node, so the user must take his own ref
104  * if needed. With the exception of the creation functions, none of the
105  * other libisofs functions that return an IsoNode increment its
106  * refcount. This is responsablity of the client, if (s)he needs it.
107  */
108  int refcount;
109 
110  /** Type of the IsoNode, do not confuse with mode */
111  enum IsoNodeType type;
112 
113  char *name; /**< Real name, in default charset */
114 
115  mode_t mode; /**< protection */
116  uid_t uid; /**< user ID of owner */
117  gid_t gid; /**< group ID of owner */
118 
119  /* TODO #00001 : consider adding new timestamps */
120  time_t atime; /**< time of last access */
121  time_t mtime; /**< time of last modification */
122  time_t ctime; /**< time of last status change */
123 
124  int hidden; /**< whether the node will be hidden, see IsoHideNodeFlag */
125 
126  IsoDir *parent; /**< parent node, NULL for root */
127 
128  /*
129  * Pointer to the linked list of children in a dir.
130  */
132 
133  /**
134  * Extended information for the node.
135  */
137 };
138 
139 struct Iso_Dir
140 {
142 
143  size_t nchildren; /**< The number of children of this directory. */
144  IsoNode *children; /**< list of children. ptr to first child */
145 };
146 
147 /* IMPORTANT: Any change must be reflected by iso_tree_clone_file. */
148 struct Iso_File
149 {
151 
152  /* 1 = The node was loaded from an existing ISO image and still refers
153  to its data content there.
154  */
155  unsigned int from_old_session : 1;
156 
157  /* 1 = The node got attributed a weight by iso_node_set_sort_weight().
158  */
159  unsigned int explicit_weight : 1;
160 
161  /**
162  * It sorts the order in which the file data is written to the CD image.
163  * Higher weighting files are written at the beginning of image
164  */
166  IsoStream *stream; /* Knows fs_id, st_dev, and st_ino */
167 };
168 
170 {
172 
173  char *dest;
174 
175  /* If the IsoNode represents an object in an existing filesystem then
176  the following three numbers should unique identify it.
177  (0,0,0) will always be taken as unique.
178  */
179  unsigned int fs_id;
180  dev_t st_dev;
181  ino_t st_ino;
182 };
183 
185 {
187  dev_t dev;
188 
189  /* If the IsoNode represents an object in an existing filesystem then
190  the following three numbers should unique identify it.
191  (0,0,0) will always be taken as unique.
192  */
193  unsigned int fs_id;
194  dev_t st_dev;
195  ino_t st_ino;
196 };
197 
199 {
200 
201  int (*next)(IsoDirIter *iter, IsoNode **node);
202 
203  int (*has_next)(IsoDirIter *iter);
204 
205  void (*free)(IsoDirIter *iter);
206 
207  int (*take)(IsoDirIter *iter);
208 
209  int (*remove)(IsoDirIter *iter);
210 
211  /**
212  * This is called just before remove a node from a directory. The iterator
213  * may want to update its internal state according to this.
214  */
215  void (*notify_child_taken)(IsoDirIter *iter, IsoNode *node);
216 };
217 
218 /**
219  * An iterator for directory children.
220  */
222 {
223  struct iso_dir_iter_iface *class;
224 
225  /* the directory this iterator iterates over */
227 
228  void *data;
229 };
230 
231 int iso_node_new_root(IsoDir **root);
232 
233 /**
234  * Create a new IsoDir. Attributes, uid/gid, timestamps, etc are set to
235  * default (0) values. You must set them.
236  *
237  * @param name
238  * Name for the node. It is not strdup() so you shouldn't use this
239  * reference when this function returns successfully. NULL is not
240  * allowed.
241  * @param dir
242  *
243  * @return
244  * 1 on success, < 0 on error.
245  */
246 int iso_node_new_dir(char *name, IsoDir **dir);
247 
248 /**
249  * Create a new file node. Attributes, uid/gid, timestamps, etc are set to
250  * default (0) values. You must set them.
251  *
252  * @param name
253  * Name for the node. It is not strdup() so you shouldn't use this
254  * reference when this function returns successfully. NULL is not
255  * allowed.
256  * @param stream
257  * Source for file contents. The reference is taken by the node,
258  * you must call iso_stream_ref() if you need your own ref.
259  * @return
260  * 1 on success, < 0 on error.
261  */
262 int iso_node_new_file(char *name, IsoStream *stream, IsoFile **file);
263 
264 /**
265  * Creates a new IsoSymlink node. Attributes, uid/gid, timestamps, etc are set
266  * to default (0) values. You must set them.
267  *
268  * @param name
269  * name for the new symlink. It is not strdup() so you shouldn't use this
270  * reference when this function returns successfully. NULL is not
271  * allowed.
272  * @param dest
273  * destination of the link. It is not strdup() so you shouldn't use this
274  * reference when this function returns successfully. NULL is not
275  * allowed.
276  * @param link
277  * place where to store a pointer to the newly created link.
278  * @return
279  * 1 on success, < 0 otherwise
280  */
281 int iso_node_new_symlink(char *name, char *dest, IsoSymlink **link);
282 
283 /**
284  * Create a new special file node. As far as libisofs concerns,
285  * an special file is a block device, a character device, a FIFO (named pipe)
286  * or a socket. You can choose the specific kind of file you want to add
287  * by setting mode properly (see man 2 stat).
288  *
289  * Note that special files are only written to image when Rock Ridge
290  * extensions are enabled. Moreover, a special file is just a directory entry
291  * in the image tree, no data is written beyond that.
292  *
293  * Owner and hidden atts are taken from parent. You can modify any of them
294  * later.
295  *
296  * @param name
297  * name for the new special file. It is not strdup() so you shouldn't use
298  * this reference when this function returns successfully. NULL is not
299  * allowed.
300  * @param mode
301  * file type and permissions for the new node. Note that you can't
302  * specify any kind of file here, only special types are allowed. i.e,
303  * S_IFSOCK, S_IFBLK, S_IFCHR and S_IFIFO are valid types; S_IFLNK,
304  * S_IFREG and S_IFDIR aren't.
305  * @param dev
306  * device ID, equivalent to the st_rdev field in man 2 stat.
307  * @param special
308  * place where to store a pointer to the newly created special file.
309  * @return
310  * 1 on success, < 0 otherwise
311  */
312 int iso_node_new_special(char *name, mode_t mode, dev_t dev,
313  IsoSpecial **special);
314 
315 /**
316  * Check if a given name is valid for an iso node.
317  *
318  * @return
319  * 1 if yes, <0 if not. The value is a specific ISO_* error code.
320  */
321 int iso_node_is_valid_name(const char *name);
322 
323 /**
324  * Check if a given path is valid for the destination of a link.
325  *
326  * @return
327  * 1 if yes, 0 if not
328  */
329 int iso_node_is_valid_link_dest(const char *dest);
330 
331 /**
332  * Find the position where to insert a node
333  *
334  * @param dir
335  * A valid dir. It can't be NULL
336  * @param name
337  * The node name to search for. It can't be NULL
338  * @param pos
339  * Will be filled with the position where to insert. It can't be NULL
340  */
341 void iso_dir_find(IsoDir *dir, const char *name, IsoNode ***pos);
342 
343 /**
344  * Check if a node with the given name exists in a dir.
345  *
346  * @param dir
347  * A valid dir. It can't be NULL
348  * @param name
349  * The node name to search for. It can't be NULL
350  * @param pos
351  * If not NULL, will be filled with the position where to insert. If the
352  * node exists, (**pos) will refer to the given node.
353  * @return
354  * 1 if node exists, 0 if not
355  */
356 int iso_dir_exists(IsoDir *dir, const char *name, IsoNode ***pos);
357 
358 /**
359  * Inserts a given node in a dir, at the specified position.
360  *
361  * @param dir
362  * Dir where to insert. It can't be NULL
363  * @param node
364  * The node to insert. It can't be NULL
365  * @param pos
366  * Position where the node will be inserted. It is a pointer previously
367  * obtained with a call to iso_dir_exists() or iso_dir_find().
368  * It can't be NULL.
369  * @param replace
370  * Whether to replace an old node with the same name with the new node.
371  * @return
372  * If success, number of children in dir. < 0 on error
373  */
374 int iso_dir_insert(IsoDir *dir, IsoNode *node, IsoNode **pos,
375  enum iso_replace_mode replace);
376 
377 /**
378  * Add a new iterator to the registry. The iterator register keeps track of
379  * all iterators being used, and are notified when directory structure
380  * changes.
381  */
383 
384 /**
385  * Unregister a directory iterator.
386  */
388 
389 void iso_notify_dir_iters(IsoNode *node, int flag);
390 
391 
392 /**
393  * See API function iso_node_set_permissions()
394  *
395  * @param flag bit0= do not adjust ACL
396  * @return >0 success , <0 error
397  */
398 int iso_node_set_perms_internal(IsoNode *node, mode_t mode, int flag);
399 
400 
401 /**
402  * Like iso_node_get_acl_text() with param node replaced by aa_string and
403  * st_mode from where to obtain the ACLs. All other parameter specs apply.
404  */
405 int iso_aa_get_acl_text(unsigned char *aa_string, mode_t st_mode,
406  char **access_text, char **default_text, int flag);
407 
408 /**
409  * Backend of iso_node_get_attrs() with parameter node replaced by the
410  * AAIP string from where to get the attribute list.
411  * All other parameter specs apply.
412  */
413 int iso_aa_get_attrs(unsigned char *aa_string, size_t *num_attrs,
414  char ***names, size_t **value_lengths, char ***values, int flag);
415 
416 /**
417  * Search given name. Eventually calloc() and copy value. Add trailing 0 byte
418  * for caller convenience.
419  *
420  * @return 1= found , 0= not found , <0 error
421  */
422 int iso_aa_lookup_attr(unsigned char *aa_string, char *name,
423  size_t *value_length, char **value, int flag);
424 
425 
426 /**
427  * Function to identify and manage ZF parameters which do not stem from ZF
428  * fields (those are known to the FileSource) and do not stem from filters
429  * ("ziso" knows them globally, "osiz" knows them individually) but rather
430  * from an inspection of the file content header for zisofs magic number and
431  * plausible parameters.
432  * The parameters get attached in struct zisofs_zf_info as xinfo to an IsoNode.
433  */
434 int zisofs_zf_xinfo_func(void *data, int flag);
435 
436 /**
437  * Parameter structure which is to be managed by zisofs_zf_xinfo_func.
438  */
443  uint8_t zisofs_algo[2];
444 };
445 
446 /**
447  * Checks whether a file effectively bears a zisofs file header and eventually
448  * marks this by a struct zisofs_zf_info as xinfo of the file node.
449  * @param flag bit0= inquire the most original stream of the file
450  * bit1= permission to overwrite existing zisofs_zf_info
451  * bit2= if no zisofs header is found:
452  create xinfo with parameters which indicate no zisofs
453  * @return 1= zf xinfo added, 0= no zisofs data found ,
454  * 2= found existing zf xinfo and flag bit1 was not set
455  * <0 means error
456  */
457 int iso_file_zf_by_magic(IsoFile *file, int flag);
458 
459 /*
460  * @param flag
461  * bit0= do only retrieve id if node is in imported ISO image
462  * or has an explicit xinfo inode number
463  * @return
464  * 1= reply is valid from stream, 2= reply is valid from xinfo
465  * 0= no id available, <0= error
466  * (fs_id, dev_id, ino_id) will be (0,0,0) in case of return <= 0
467  */
468 int iso_node_get_id(IsoNode *node, unsigned int *fs_id, dev_t *dev_id,
469  ino_t *ino_id, int flag);
470 
471 /* Set a new unique inode ISO image number to the given node.
472  * This number shall eventually persist during image generation.
473  */
474 int iso_node_set_unique_id(IsoNode *node, IsoImage *image, int flag);
475 
476 /* Use this with extreme care. Duplicate inode numbers will indicate hardlink
477  * relationship between the nodes.
478  */
479 int iso_node_set_ino(IsoNode *node, ino_t ino, int flag);
480 
481 /*
482  * @param flag
483  * bit0= compare stat properties and attributes
484  * bit1= treat all nodes with image ino == 0 as unique
485  * (those with 0,0,0 are treated as unique anyway)
486  */
487 int iso_node_cmp_flag(IsoNode *n1, IsoNode *n2, int flag);
488 
489 
490 /**
491  * Set the checksum index (typically coming from IsoFileSrc.checksum_index)
492  * of a regular file node. The index is encoded as xattr "isofs.cx" with
493  * four bytes of value.
494  */
495 int iso_file_set_isofscx(IsoFile *file, unsigned int checksum_index,
496  int flag);
497 
498 
499 /**
500  * Set the checksum area description. node should be the root node.
501  * It is encoded as xattr "isofs.ca".
502  */
503 int iso_root_set_isofsca(IsoNode *node, uint32_t start_lba, uint32_t end_lba,
504  uint32_t count, uint32_t size, char *typetext,
505  int flag);
506 
507 /**
508  * Get the checksum area description. node should be the root node.
509  * It is encoded as xattr "isofs.ca".
510  */
511 int iso_root_get_isofsca(IsoNode *node, uint32_t *start_lba, uint32_t *end_lba,
512  uint32_t *count, uint32_t *size, char typetext[81],
513  int flag);
514 
515 
516 /**
517  * Record and get truncation parameters as of iso_image_set_truncate_mode() by
518  * "isofs.nt".
519  */
520 int iso_root_set_isofsnt(IsoNode *node, uint32_t truncate_mode,
521  uint32_t truncate_length, int flag);
522 int iso_root_get_isofsnt(IsoNode *node, uint32_t *truncate_mode,
523  uint32_t *truncate_length, int flag);
524 
525 
526 /**
527  * Copy the xinfo list from one node to the another.
528  */
529 int iso_node_clone_xinfo(IsoNode *from_node, IsoNode *to_node, int flag);
530 
531 
532 /**
533  * The iso_node_xinfo_func instance which governs the storing of the inode
534  * number from Rock Ridge field PX.
535  */
536 int iso_px_ino_xinfo_func(void *data, int flag);
537 
538 /* The iso_node_xinfo_cloner function which gets associated to
539  * iso_px_ino_xinfo_func by iso_init() resp. iso_init_with_flag() via
540  * iso_node_xinfo_make_clonable()
541  */
542 int iso_px_ino_xinfo_cloner(void *old_data, void **new_data, int flag);
543 
544 
545 /* Function to identify and manage ZF parameters of zisofs compression.
546  * data is supposed to be a pointer to struct zisofs_zf_info
547  */
548 int zisofs_zf_xinfo_func(void *data, int flag);
549 
550 /* The iso_node_xinfo_cloner function which gets associated to
551  * zisofs_zf_xinfo_func by iso_init() resp. iso_init_with_flag() via
552  * iso_node_xinfo_make_clonable()
553  */
554 int zisofs_zf_xinfo_cloner(void *old_data, void **new_data, int flag);
555 
556 
557 /* Performing search for possibly truncated node name.
558  */
559 int iso_dir_get_node_trunc(IsoDir *dir, int truncate_length,
560  const char *name, IsoNode **node);
561 
562 
563 #endif /*LIBISO_NODE_H_*/
IsoNodeType
Definition: libisofs.h:228
int(* iso_node_xinfo_func)(void *data, int flag)
Definition: libisofs.h:4838
iso_replace_mode
Definition: libisofs.h:347
int iso_px_ino_xinfo_cloner(void *old_data, void **new_data, int flag)
Definition: node.c:2571
int iso_dir_get_node_trunc(IsoDir *dir, int truncate_length, const char *name, IsoNode **node)
Definition: node.c:654
int iso_root_get_isofsnt(IsoNode *node, uint32_t *truncate_mode, uint32_t *truncate_length, int flag)
Definition: node.c:3001
int iso_node_get_id(IsoNode *node, unsigned int *fs_id, dev_t *dev_id, ino_t *ino_id, int flag)
Definition: node.c:2592
int iso_root_set_isofsca(IsoNode *node, uint32_t start_lba, uint32_t end_lba, uint32_t count, uint32_t size, char *typetext, int flag)
Definition: node.c:2910
int iso_px_ino_xinfo_func(void *data, int flag)
Definition: node.c:2559
int iso_node_is_valid_link_dest(const char *dest)
Definition: node.c:1283
int iso_file_set_isofscx(IsoFile *file, unsigned int checksum_index, int flag)
Definition: node.c:2887
int iso_node_new_dir(char *name, IsoDir **dir)
Definition: node.c:1481
int iso_aa_get_attrs(unsigned char *aa_string, size_t *num_attrs, char ***names, size_t **value_lengths, char ***values, int flag)
Definition: node.c:1647
int iso_node_new_file(char *name, IsoStream *stream, IsoFile **file)
Definition: node.c:1507
int iso_dir_insert(IsoDir *dir, IsoNode *node, IsoNode **pos, enum iso_replace_mode replace)
Definition: node.c:1349
int zisofs_zf_xinfo_cloner(void *old_data, void **new_data, int flag)
Definition: node.c:2423
int iso_node_is_valid_name(const char *name)
Definition: node.c:1245
int iso_root_set_isofsnt(IsoNode *node, uint32_t truncate_mode, uint32_t truncate_length, int flag)
Definition: node.c:2982
int iso_node_new_special(char *name, mode_t mode, dev_t dev, IsoSpecial **special)
Definition: node.c:1573
int iso_dir_exists(IsoDir *dir, const char *name, IsoNode ***pos)
Definition: node.c:1338
int iso_node_clone_xinfo(IsoNode *from_node, IsoNode *to_node, int flag)
Definition: node.c:286
int iso_node_new_symlink(char *name, char *dest, IsoSymlink **link)
Definition: node.c:1538
int iso_aa_lookup_attr(unsigned char *aa_string, char *name, size_t *value_length, char **value, int flag)
Definition: node.c:1724
int iso_node_cmp_flag(IsoNode *n1, IsoNode *n2, int flag)
Definition: node.c:2743
int iso_root_get_isofsca(IsoNode *node, uint32_t *start_lba, uint32_t *end_lba, uint32_t *count, uint32_t *size, char typetext[81], int flag)
Definition: node.c:2941
int iso_node_set_perms_internal(IsoNode *node, mode_t mode, int flag)
Definition: node.c:430
void iso_dir_iter_unregister(IsoDirIter *iter)
Definition: node.c:1434
int iso_dir_iter_register(IsoDirIter *iter)
Definition: node.c:1418
int iso_file_zf_by_magic(IsoFile *file, int flag)
Definition: node.c:2448
int iso_node_new_root(IsoDir **root)
Definition: node.c:1460
int zisofs_zf_xinfo_func(void *data, int flag)
Definition: node.c:2411
void iso_notify_dir_iters(IsoNode *node, int flag)
Definition: node.c:1448
void iso_dir_find(IsoDir *dir, const char *name, IsoNode ***pos)
Definition: node.c:1330
int iso_node_set_unique_id(IsoNode *node, IsoImage *image, int flag)
Definition: node.c:2718
int iso_node_set_ino(IsoNode *node, ino_t ino, int flag)
Definition: node.c:2672
int iso_aa_get_acl_text(unsigned char *aa_string, mode_t st_mode, char **access_text, char **default_text, int flag)
Definition: node.c:2180
IsoDir * dir
Definition: node.h:226
void * data
Definition: node.h:228
Definition: node.h:140
IsoNode * children
Definition: node.h:144
IsoNode node
Definition: node.h:141
size_t nchildren
Definition: node.h:143
Definition: node.h:149
IsoNode node
Definition: node.h:150
IsoStream * stream
Definition: node.h:166
int sort_weight
Definition: node.h:165
unsigned int from_old_session
Definition: node.h:155
unsigned int explicit_weight
Definition: node.h:159
Definition: node.h:100
int refcount
Definition: node.h:108
gid_t gid
Definition: node.h:117
time_t ctime
Definition: node.h:122
uid_t uid
Definition: node.h:116
char * name
Definition: node.h:113
time_t atime
Definition: node.h:120
IsoExtendedInfo * xinfo
Definition: node.h:136
IsoDir * parent
Definition: node.h:126
enum IsoNodeType type
Definition: node.h:111
mode_t mode
Definition: node.h:115
int hidden
Definition: node.h:124
IsoNode * next
Definition: node.h:131
time_t mtime
Definition: node.h:121
ino_t st_ino
Definition: node.h:195
dev_t st_dev
Definition: node.h:194
unsigned int fs_id
Definition: node.h:193
dev_t dev
Definition: node.h:187
IsoNode node
Definition: node.h:186
void(* free)(IsoDirIter *iter)
Definition: node.h:205
int(* remove)(IsoDirIter *iter)
Definition: node.h:209
void(* notify_child_taken)(IsoDirIter *iter, IsoNode *node)
Definition: node.h:215
int(* take)(IsoDirIter *iter)
Definition: node.h:207
int(* next)(IsoDirIter *iter, IsoNode **node)
Definition: node.h:201
int(* has_next)(IsoDirIter *iter)
Definition: node.h:203
iso_node_xinfo_func process
Definition: node.h:88
IsoExtendedInfo * next
Definition: node.h:72
void * data
Definition: node.h:93
uint8_t header_size_div4
Definition: node.h:441
uint8_t block_size_log2
Definition: node.h:442
uint8_t zisofs_algo[2]
Definition: node.h:443
uint64_t uncompressed_size
Definition: node.h:440