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)  

rockridge.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2007 Vreixo Formoso
3  * Copyright (c) 2007 Mario Danic
4  * Copyright (c) 2009 - 2020 Thomas Schmitt
5  *
6  * This file is part of the libisofs project; you can redistribute it and/or
7  * modify it under the terms of the GNU General Public License version 2
8  * or later as published by the Free Software Foundation.
9  * See COPYING file for details.
10  */
11 
12 /**
13  * This header defines the functions and structures needed to add RockRidge
14  * extensions to an ISO image. It also handles AAIP and zisofs extensions.
15  *
16  * References:
17  *
18  * - SUSP (IEEE 1281).
19  * System Use Sharing Protocol, draft standard version 1.12.
20  * See ftp://ftp.ymi.com/pub/rockridge/susp112.ps
21  *
22  * - RRIP (IEEE 1282)
23  * Rock Ridge Interchange Protocol, Draft Standard version 1.12.
24  * See ftp://ftp.ymi.com/pub/rockridge/rrip112.ps
25  *
26  * - ECMA-119 (ISO-9660)
27  * Volume and File Structure of CDROM for Information Interchange. See
28  * http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-119.pdf
29  *
30  * - AAIP
31  * Arbitrary Attribute Interchange Protocol. See doc/susp_aaip_2_0.txt
32  *
33  * - zisofs
34  * Blockwise compression of data file content with transparent read support
35  * in the Linux kernel. See doc/zisofs_format.txt
36  *
37  */
38 
39 #ifndef LIBISO_ROCKRIDGE_H
40 #define LIBISO_ROCKRIDGE_H
41 
42 #include "ecma119.h"
43 
44 
45 #define SUSP_SIG(entry, a, b) ((entry->sig[0] == a) && (entry->sig[1] == b))
46 
47 /**
48  * This contains the information about the System Use Fields (SUSP, 4.1),
49  * that will be written in the System Use Areas, both in the ISO directory
50  * record System Use field (ECMA-119, 9.1.13) or in a Continuation Area as
51  * defined by SUSP.
52  */
53 struct susp_info
54 {
55  /** Number of SUSP fields in the System Use field */
56  size_t n_susp_fields;
57  uint8_t **susp_fields;
58 
59  /** Length of the part of the SUSP area that fits in the dirent. */
60  int suf_len;
61 
62  /** Length of the part of the SUSP area that will go in a CE area. */
63  uint32_t ce_block;
64  uint32_t ce_len;
65 
66  /* Storage for Continuation Area for a whole directory */
68  uint8_t **ce_susp_fields;
69 
70  /* The number of allocated members in ce_susp_fields */
72 
73  /* Marks the start index in ce_susp_fields of the current node */
75 
76 };
77 
78 /* Step to increase allocated size of susp_info.ce_susp_fields */
79 #define ISO_SUSP_CE_ALLOC_STEP 16
80 
81 
82 /* SUSP 5.1 */
83 struct susp_CE {
84  uint8_t block[8];
85  uint8_t offset[8];
86  uint8_t len[8];
87 };
88 
89 /* SUSP 5.3 */
90 struct susp_SP {
91  uint8_t be[1];
92  uint8_t ef[1];
93  uint8_t len_skp[1];
94 };
95 
96 /* SUSP 5.5 */
97 struct susp_ER {
98  uint8_t len_id[1];
99  uint8_t len_des[1];
100  uint8_t len_src[1];
101  uint8_t ext_ver[1];
102  uint8_t ext_id[1]; /*< up to len_id bytes */
103  /* ext_des, ext_src */
104 };
105 
106 /** POSIX file attributes (RRIP, 4.1.1) */
107 struct rr_PX {
108  uint8_t mode[8];
109  uint8_t links[8];
110  uint8_t uid[8];
111  uint8_t gid[8];
112  uint8_t serial[8];
113 };
114 
115 /** Time stamps for a file (RRIP, 4.1.6) */
116 struct rr_TF {
117  uint8_t flags[1];
118  uint8_t t_stamps[1];
119 };
120 
121 /** Info for character and block device (RRIP, 4.1.2) */
122 struct rr_PN {
123  uint8_t high[8];
124  uint8_t low[8];
125 };
126 
127 /** Alternate name (RRIP, 4.1.4) */
128 struct rr_NM {
129  uint8_t flags[1];
130  uint8_t name[1];
131 };
132 
133 /** Link for a relocated directory (RRIP, 4.1.5.1) */
134 struct rr_CL {
135  uint8_t child_loc[8];
136 };
137 
138 /** Sim link (RRIP, 4.1.3) */
139 struct rr_SL {
140  uint8_t flags[1];
141  uint8_t comps[1];
142 };
143 
144 
145 /** Outdated Arbitrary Attribute (AAIP, see doc/susp_aaip_1_0.txt)
146  * It collided with pre-SUSP Apple AA field.
147  */
148 struct aaip_AA {
149  uint8_t flags[1];
150  uint8_t comps[1];
151 };
152 
153 /** Arbitrary Attribute (AAIP, see doc/susp_aaip_2_0.txt) */
154 struct aaip_AL {
155  uint8_t flags[1];
156  uint8_t comps[1];
157 };
158 
159 
160 /** zisofs entry (see doc/zisofs_format.txt) */
161 struct zisofs_ZF {
162  uint8_t parameters[1]; /* begins with BP 5 */
163 };
164 
165 
166 /**
167  * Struct for a SUSP System User Entry (SUSP, 4.1)
168  */
170 {
171  uint8_t sig[2];
172  uint8_t len_sue[1];
173  uint8_t version[1];
174  union {
175  struct susp_CE CE;
176  struct susp_SP SP;
177  struct susp_ER ER;
178  struct rr_PX PX;
179  struct rr_TF TF;
180  struct rr_PN PN;
181  struct rr_NM NM;
182  struct rr_CL CL;
183  struct rr_SL SL;
184  struct aaip_AA AA;
185  struct aaip_AL AL;
186  struct zisofs_ZF ZF;
187  } data; /* 5 to 4+len_sue */
188 };
189 
190 /**
191  * Compute the length needed for write all RR and SUSP entries for a given
192  * node.
193  *
194  * @param type
195  * 0 normal entry, 1 "." entry for that node (it is a dir), 2 ".."
196  * for that node (i.e., it will refer to the parent)
197  * @param space
198  * Available space in the System Use Area for the directory record.
199  * @param ce
200  * Will be filled with the space needed in a CE
201  * @param base_ce
202  * Fill of continuation area by previous nodes of same dir
203  * @return
204  * The size needed for the RR entries in the System Use Area
205  */
206 size_t rrip_calc_len(Ecma119Image *t, Ecma119Node *n, int type, size_t space,
207  size_t *ce, size_t base_ce);
208 
209 /**
210  * Fill a struct susp_info with the RR/SUSP entries needed for a given
211  * node.
212  *
213  * @param type
214  * 0 normal entry, 1 "." entry for that node (it is a dir), 2 ".."
215  * for that node (i.e., it will refer to the parent)
216  * @param space
217  * Available space in the System Use Area for the directory record.
218  * @param info
219  * Pointer to the struct susp_info where the entries will be stored.
220  * If some entries need to go to a Continuation Area, they will be added
221  * to the existing ce_susp_fields, and ce_len will be incremented
222  * properly. Please ensure ce_block is initialized properly.
223  * @return
224  * 1 success, < 0 error
225  */
226 int rrip_get_susp_fields(Ecma119Image *t, Ecma119Node *n, int type,
227  size_t space, struct susp_info *info);
228 
229 /**
230  * Write the given SUSP fields into buf. Note that Continuation Area
231  * fields are not written.
232  * If info does not contain any SUSP entry this function just return.
233  * After written, the info susp_fields array will be freed, and the counters
234  * updated properly.
235  */
236 void rrip_write_susp_fields(Ecma119Image *t, struct susp_info *info,
237  uint8_t *buf);
238 
239 /**
240  * Write the Continuation Area entries for the given struct susp_info, using
241  * the iso_write() function.
242  * After written, the ce_susp_fields array will be freed.
243  */
245 
246 /**
247  * The SUSP iterator is used to iterate over the System User Entries
248  * of a ECMA-168 directory record.
249  * It takes care about Continuation Areas, handles the end of the different
250  * system user entries and skip padding areas. Thus, using an iteration
251  * we are accessing just to the meaning entries.
252  */
253 typedef struct susp_iterator SuspIterator;
254 
255 SuspIterator *
257  uint32_t fs_blocks, uint8_t len_skp, int msgid);
258 
259 /**
260  * Get the next SUSP System User Entry using given iterator.
261  *
262  * @param sue
263  * Pointer to the next susp entry. It refers to an internal buffer and
264  * it's not guaranteed to be allocated after calling susp_iter_next()
265  * again. Thus, if you need to keep some entry you have to do a copy.
266  * @return
267  * 1 on success, 0 if no more entries, < 0 error
268  */
269 int susp_iter_next(SuspIterator *iter, struct susp_sys_user_entry **sue,
270  int flag);
271 
272 /**
273  * Free a given susp iterator.
274  */
275 void susp_iter_free(SuspIterator *iter);
276 
277 
278 /**
279  * Fills a struct stat with the values of a Rock Ridge PX entry (RRIP, 4.1.1).
280  *
281  * @return
282  * < 0 on error
283  * 1 on success with no inode number,
284  * 2 on success with inode number,
285  */
286 int read_rr_PX(struct susp_sys_user_entry *px, struct stat *st);
287 
288 /**
289  * Fills a struct stat with the values of a Rock Ridge TF entry (RRIP, 4.1.6)
290  *
291  * @return
292  * 1 on success, < 0 on error
293  */
294 int read_rr_TF(struct susp_sys_user_entry *tf, struct stat *st);
295 
296 /**
297  * Read a RR NM entry (RRIP, 4.1.4), and appends the name stored there to
298  * the given name. You can pass a pointer to NULL as name.
299  *
300  * @return
301  * 1 on success, < 0 on error
302  */
303 int read_rr_NM(struct susp_sys_user_entry *nm, char **name, int *cont);
304 
305 /**
306  * Read a SL RR entry (RRIP, 4.1.3), checking if the destination continues.
307  *
308  * @param cont
309  * 0 not continue, 1 continue, 2 continue component
310  * @return
311  * 1 on success, < 0 on error
312  */
313 int read_rr_SL(struct susp_sys_user_entry *sl, char **dest, int *cont);
314 
315 /**
316  * Fills a struct stat with the values of a Rock Ridge PN entry (RRIP, 4.1.2).
317  *
318  * @return
319  * 1 on success, < 0 on error
320  */
321 int read_rr_PN(struct susp_sys_user_entry *pn, struct stat *st);
322 
323 
324 /**
325  * Collects the AAIP field string from single AAIP fields.
326  * (see doc/susp_aaip_1_0.txt)
327  * @param aa_string Storage location of the emerging string.
328  * Begin with *aa_string == NULL, or own malloc() storage.
329  * @param aa_size Current allocated size of aa_string.
330  * Begin with *aa_size == 0, or own storage size.
331  * @param aa_len Current occupied size of aa_string.
332  * Begin with *aa_len == 0
333  * @param prev_field Returns the index of start of the previous field
334  * in the string.
335  * @param is_done The current completion state of the AAIP field string.
336  * Fields will be ignored as soon as it is 1.
337  * Begin with *is_done == 0
338  * @param flag Unused yet. Submit 0.
339  * @return
340  * 1 on success, < 0 on error
341  */
342 int read_aaip_AA(struct susp_sys_user_entry *sue,
343  unsigned char **aa_string, size_t *aa_size, size_t *aa_len,
344  size_t *prev_field, int *is_done, int flag);
345 
346 /**
347  * Collects the AAIP field string from single AL fields.
348  * (see doc/susp_aaip_2_0.txt)
349  */
350 int read_aaip_AL(struct susp_sys_user_entry *sue,
351  unsigned char **aa_string, size_t *aa_size, size_t *aa_len,
352  size_t *prev_field, int *is_done, int flag);
353 
354 /**
355  * Reads the zisofs parameters from a ZF field (see doc/zisofs_format.txt).
356  *
357  * @return
358  * 1 on success, < 0 on error
359  */
360 int read_zisofs_ZF(struct susp_sys_user_entry *zf, uint8_t algorithm[2],
361  uint8_t *header_size_div4, uint8_t *block_size_log2,
362  uint64_t *uncompressed_size, int flag);
363 
364 /**
365  * Convert a RR filename to the requested charset.
366  * @param flag bit0= do not issue error messages
367  */
368 int iso_get_rr_name(IsoWriteOpts *opts, char *input_charset,
369  char *output_charset, int imgid,
370  char *str, char **name, int flag);
371 
372 #endif /* LIBISO_ROCKRIDGE_H */
int read_rr_TF(struct susp_sys_user_entry *tf, struct stat *st)
SuspIterator * susp_iter_new(IsoDataSource *src, struct ecma119_dir_record *record, uint32_t fs_blocks, uint8_t len_skp, int msgid)
int rrip_get_susp_fields(Ecma119Image *t, Ecma119Node *n, int type, size_t space, struct susp_info *info)
Definition: rockridge.c:1636
int read_zisofs_ZF(struct susp_sys_user_entry *zf, uint8_t algorithm[2], uint8_t *header_size_div4, uint8_t *block_size_log2, uint64_t *uncompressed_size, int flag)
void susp_iter_free(SuspIterator *iter)
int read_rr_SL(struct susp_sys_user_entry *sl, char **dest, int *cont)
int read_aaip_AL(struct susp_sys_user_entry *sue, unsigned char **aa_string, size_t *aa_size, size_t *aa_len, size_t *prev_field, int *is_done, int flag)
int read_rr_PX(struct susp_sys_user_entry *px, struct stat *st)
size_t rrip_calc_len(Ecma119Image *t, Ecma119Node *n, int type, size_t space, size_t *ce, size_t base_ce)
Definition: rockridge.c:1483
int susp_iter_next(SuspIterator *iter, struct susp_sys_user_entry **sue, int flag)
int iso_get_rr_name(IsoWriteOpts *opts, char *input_charset, char *output_charset, int imgid, char *str, char **name, int flag)
Definition: rockridge.c:367
int read_aaip_AA(struct susp_sys_user_entry *sue, unsigned char **aa_string, size_t *aa_size, size_t *aa_len, size_t *prev_field, int *is_done, int flag)
int rrip_write_ce_fields(Ecma119Image *t, struct susp_info *info)
Definition: rockridge.c:2270
void rrip_write_susp_fields(Ecma119Image *t, struct susp_info *info, uint8_t *buf)
Definition: rockridge.c:2235
int read_rr_PN(struct susp_sys_user_entry *pn, struct stat *st)
int read_rr_NM(struct susp_sys_user_entry *nm, char **name, int *cont)
uint8_t comps[1]
Definition: rockridge.h:150
uint8_t flags[1]
Definition: rockridge.h:149
uint8_t comps[1]
Definition: rockridge.h:156
uint8_t flags[1]
Definition: rockridge.h:155
uint8_t child_loc[8]
Definition: rockridge.h:135
uint8_t name[1]
Definition: rockridge.h:130
uint8_t flags[1]
Definition: rockridge.h:129
uint8_t low[8]
Definition: rockridge.h:124
uint8_t high[8]
Definition: rockridge.h:123
uint8_t mode[8]
Definition: rockridge.h:108
uint8_t links[8]
Definition: rockridge.h:109
uint8_t uid[8]
Definition: rockridge.h:110
uint8_t serial[8]
Definition: rockridge.h:112
uint8_t gid[8]
Definition: rockridge.h:111
uint8_t comps[1]
Definition: rockridge.h:141
uint8_t flags[1]
Definition: rockridge.h:140
uint8_t t_stamps[1]
Definition: rockridge.h:118
uint8_t flags[1]
Definition: rockridge.h:117
uint8_t block[8]
Definition: rockridge.h:84
uint8_t offset[8]
Definition: rockridge.h:85
uint8_t len[8]
Definition: rockridge.h:86
uint8_t ext_ver[1]
Definition: rockridge.h:101
uint8_t len_src[1]
Definition: rockridge.h:100
uint8_t len_id[1]
Definition: rockridge.h:98
uint8_t len_des[1]
Definition: rockridge.h:99
uint8_t ext_id[1]
Definition: rockridge.h:102
uint8_t be[1]
Definition: rockridge.h:91
uint8_t len_skp[1]
Definition: rockridge.h:93
uint8_t ef[1]
Definition: rockridge.h:92
uint8_t ** ce_susp_fields
Definition: rockridge.h:68
size_t n_ce_susp_fields
Definition: rockridge.h:67
size_t n_susp_fields
Definition: rockridge.h:56
uint32_t ce_block
Definition: rockridge.h:63
uint32_t ce_len
Definition: rockridge.h:64
size_t alloc_ce_susp_fields
Definition: rockridge.h:71
size_t current_ce_start
Definition: rockridge.h:74
uint8_t ** susp_fields
Definition: rockridge.h:57
int suf_len
Definition: rockridge.h:60
IsoDataSource * src
uint32_t fs_blocks
Definition: rockridge.h:170
uint8_t len_sue[1]
Definition: rockridge.h:172
struct rr_SL SL
Definition: rockridge.h:183
uint8_t sig[2]
Definition: rockridge.h:171
struct rr_PX PX
Definition: rockridge.h:178
struct susp_ER ER
Definition: rockridge.h:177
struct zisofs_ZF ZF
Definition: rockridge.h:186
struct aaip_AA AA
Definition: rockridge.h:184
struct aaip_AL AL
Definition: rockridge.h:185
struct rr_CL CL
Definition: rockridge.h:182
union susp_sys_user_entry::@6 data
uint8_t version[1]
Definition: rockridge.h:173
struct rr_TF TF
Definition: rockridge.h:179
struct rr_PN PN
Definition: rockridge.h:180
struct rr_NM NM
Definition: rockridge.h:181
struct susp_SP SP
Definition: rockridge.h:176
struct susp_CE CE
Definition: rockridge.h:175
uint8_t parameters[1]
Definition: rockridge.h:162