You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
9048 lines
314 KiB
9048 lines
314 KiB
|
|
#ifndef LIBISO_LIBISOFS_H_ |
|
#define LIBISO_LIBISOFS_H_ |
|
|
|
/* |
|
* Copyright (c) 2007-2008 Vreixo Formoso, Mario Danic |
|
* Copyright (c) 2009-2016 Thomas Schmitt |
|
* |
|
* This file is part of the libisofs project; you can redistribute it and/or |
|
* modify it under the terms of the GNU General Public License version 2 |
|
* or later as published by the Free Software Foundation. |
|
* See COPYING file for details. |
|
*/ |
|
|
|
/* Important: If you add a public API function then add its name to file |
|
libisofs/libisofs.ver |
|
*/ |
|
|
|
#ifdef __cplusplus |
|
extern "C" { |
|
#endif |
|
|
|
/* |
|
* |
|
* Applications must use 64 bit off_t. |
|
* E.g. on 32-bit GNU/Linux by defining |
|
* #define _LARGEFILE_SOURCE |
|
* #define _FILE_OFFSET_BITS 64 |
|
* The minimum requirement is to interface with the library by 64 bit signed |
|
* integers where libisofs.h or libisoburn.h prescribe off_t. |
|
* Failure to do so may result in surprising malfunction or memory faults. |
|
* |
|
* Application files which include libisofs/libisofs.h must provide |
|
* definitions for uint32_t and uint8_t. |
|
* This can be achieved either: |
|
* - by using autotools which will define HAVE_STDINT_H or HAVE_INTTYPES_H |
|
* according to its ./configure tests, |
|
* - or by defining the macros HAVE_STDINT_H or HAVE_INTTYPES_H according |
|
* to the local situation, |
|
* - or by appropriately defining uint32_t and uint8_t by other means, |
|
* e.g. by including inttypes.h before including libisofs.h |
|
*/ |
|
#ifdef HAVE_STDINT_H |
|
#include <stdint.h> |
|
#else |
|
#ifdef HAVE_INTTYPES_H |
|
#include <inttypes.h> |
|
#endif |
|
#endif |
|
|
|
|
|
/* |
|
* Normally this API is operated via public functions and opaque object |
|
* handles. But it also exposes several C structures which may be used to |
|
* provide custom functionality for the objects of the API. The same |
|
* structures are used for internal objects of libisofs, too. |
|
* You are not supposed to manipulate the entrails of such objects if they |
|
* are not your own custom extensions. |
|
* |
|
* See for an example IsoStream = struct iso_stream below. |
|
*/ |
|
|
|
|
|
#include <sys/stat.h> |
|
|
|
#include <stdlib.h> |
|
|
|
/* Because AIX defines "open" as "open64". |
|
There are struct members named "open" in libisofs.h which get affected. |
|
So all includers of libisofs.h must get included fcntl.h to see the same. |
|
*/ |
|
#include <fcntl.h> |
|
|
|
|
|
/** |
|
* The following two functions and three macros are utilities to help ensuring |
|
* version match of application, compile time header, and runtime library. |
|
*/ |
|
/** |
|
* These three release version numbers tell the revision of this header file |
|
* and of the API it describes. They are memorized by applications at |
|
* compile time. |
|
* They must show the same values as these symbols in ./configure.ac |
|
* LIBISOFS_MAJOR_VERSION=... |
|
* LIBISOFS_MINOR_VERSION=... |
|
* LIBISOFS_MICRO_VERSION=... |
|
* Note to anybody who does own work inside libisofs: |
|
* Any change of configure.ac or libisofs.h has to keep up this equality ! |
|
* |
|
* Before usage of these macros on your code, please read the usage discussion |
|
* below. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
#define iso_lib_header_version_major 1 |
|
#define iso_lib_header_version_minor 4 |
|
#define iso_lib_header_version_micro 5 |
|
|
|
/** |
|
* Get version of the libisofs library at runtime. |
|
* NOTE: This function may be called before iso_init(). |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
void iso_lib_version(int *major, int *minor, int *micro); |
|
|
|
/** |
|
* Check at runtime if the library is ABI compatible with the given version. |
|
* NOTE: This function may be called before iso_init(). |
|
* |
|
* @return |
|
* 1 lib is compatible, 0 is not. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_lib_is_compatible(int major, int minor, int micro); |
|
|
|
/** |
|
* Usage discussion: |
|
* |
|
* Some developers of the libburnia project have differing opinions how to |
|
* ensure the compatibility of libaries and applications. |
|
* |
|
* It is about whether to use at compile time and at runtime the version |
|
* numbers provided here. Thomas Schmitt advises to use them. Vreixo Formoso |
|
* advises to use other means. |
|
* |
|
* At compile time: |
|
* |
|
* Vreixo Formoso advises to leave proper version matching to properly |
|
* programmed checks in the the application's build system, which will |
|
* eventually refuse compilation. |
|
* |
|
* Thomas Schmitt advises to use the macros defined here for comparison with |
|
* the application's requirements of library revisions and to eventually |
|
* break compilation. |
|
* |
|
* Both advises are combinable. I.e. be master of your build system and have |
|
* #if checks in the source code of your application, nevertheless. |
|
* |
|
* At runtime (via iso_lib_is_compatible()): |
|
* |
|
* Vreixo Formoso advises to compare the application's requirements of |
|
* library revisions with the runtime library. This is to allow runtime |
|
* libraries which are young enough for the application but too old for |
|
* the lib*.h files seen at compile time. |
|
* |
|
* Thomas Schmitt advises to compare the header revisions defined here with |
|
* the runtime library. This is to enforce a strictly monotonous chain of |
|
* revisions from app to header to library, at the cost of excluding some older |
|
* libraries. |
|
* |
|
* These two advises are mutually exclusive. |
|
*/ |
|
|
|
struct burn_source; |
|
|
|
/** |
|
* Context for image creation. It holds the files that will be added to image, |
|
* and several options to control libisofs behavior. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
typedef struct Iso_Image IsoImage; |
|
|
|
/* |
|
* A node in the iso tree, i.e. a file that will be written to image. |
|
* |
|
* It can represent any kind of files. When needed, you can get the type with |
|
* iso_node_get_type() and cast it to the appropriate subtype. Useful macros |
|
* are provided, see below. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
typedef struct Iso_Node IsoNode; |
|
|
|
/** |
|
* A directory in the iso tree. It is an special type of IsoNode and can be |
|
* casted to it in any case. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
typedef struct Iso_Dir IsoDir; |
|
|
|
/** |
|
* A symbolic link in the iso tree. It is an special type of IsoNode and can be |
|
* casted to it in any case. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
typedef struct Iso_Symlink IsoSymlink; |
|
|
|
/** |
|
* A regular file in the iso tree. It is an special type of IsoNode and can be |
|
* casted to it in any case. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
typedef struct Iso_File IsoFile; |
|
|
|
/** |
|
* An special file in the iso tree. This is used to represent any POSIX file |
|
* other that regular files, directories or symlinks, i.e.: socket, block and |
|
* character devices, and fifos. |
|
* It is an special type of IsoNode and can be casted to it in any case. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
typedef struct Iso_Special IsoSpecial; |
|
|
|
/** |
|
* The type of an IsoNode. |
|
* |
|
* When an user gets an IsoNode from an image, (s)he can use |
|
* iso_node_get_type() to get the current type of the node, and then |
|
* cast to the appropriate subtype. For example: |
|
* |
|
* ... |
|
* IsoNode *node; |
|
* res = iso_dir_iter_next(iter, &node); |
|
* if (res == 1 && iso_node_get_type(node) == LIBISO_DIR) { |
|
* IsoDir *dir = (IsoDir *)node; |
|
* ... |
|
* } |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
enum IsoNodeType { |
|
LIBISO_DIR, |
|
LIBISO_FILE, |
|
LIBISO_SYMLINK, |
|
LIBISO_SPECIAL, |
|
LIBISO_BOOT |
|
}; |
|
|
|
/* macros to check node type */ |
|
#define ISO_NODE_IS_DIR(n) (iso_node_get_type(n) == LIBISO_DIR) |
|
#define ISO_NODE_IS_FILE(n) (iso_node_get_type(n) == LIBISO_FILE) |
|
#define ISO_NODE_IS_SYMLINK(n) (iso_node_get_type(n) == LIBISO_SYMLINK) |
|
#define ISO_NODE_IS_SPECIAL(n) (iso_node_get_type(n) == LIBISO_SPECIAL) |
|
#define ISO_NODE_IS_BOOTCAT(n) (iso_node_get_type(n) == LIBISO_BOOT) |
|
|
|
/* macros for safe downcasting */ |
|
#define ISO_DIR(n) ((IsoDir*)(ISO_NODE_IS_DIR(n) ? n : NULL)) |
|
#define ISO_FILE(n) ((IsoFile*)(ISO_NODE_IS_FILE(n) ? n : NULL)) |
|
#define ISO_SYMLINK(n) ((IsoSymlink*)(ISO_NODE_IS_SYMLINK(n) ? n : NULL)) |
|
#define ISO_SPECIAL(n) ((IsoSpecial*)(ISO_NODE_IS_SPECIAL(n) ? n : NULL)) |
|
|
|
#define ISO_NODE(n) ((IsoNode*)n) |
|
|
|
/** |
|
* File section in an old image. |
|
* |
|
* @since 0.6.8 |
|
*/ |
|
struct iso_file_section |
|
{ |
|
uint32_t block; |
|
uint32_t size; |
|
}; |
|
|
|
/* If you get here because of a compilation error like |
|
|
|
/usr/include/libisofs/libisofs.h:166: error: |
|
expected specifier-qualifier-list before 'uint32_t' |
|
|
|
then see the paragraph above about the definition of uint32_t. |
|
*/ |
|
|
|
|
|
/** |
|
* Context for iterate on directory children. |
|
* @see iso_dir_get_children() |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
typedef struct Iso_Dir_Iter IsoDirIter; |
|
|
|
/** |
|
* It represents an El-Torito boot image. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
typedef struct el_torito_boot_image ElToritoBootImage; |
|
|
|
/** |
|
* An special type of IsoNode that acts as a placeholder for an El-Torito |
|
* boot catalog. Once written, it will appear as a regular file. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
typedef struct Iso_Boot IsoBoot; |
|
|
|
/** |
|
* Flag used to hide a file in the RR/ISO or Joliet tree. |
|
* |
|
* @see iso_node_set_hidden |
|
* @since 0.6.2 |
|
*/ |
|
enum IsoHideNodeFlag { |
|
/** Hide the node in the ECMA-119 / RR tree */ |
|
LIBISO_HIDE_ON_RR = 1 << 0, |
|
/** Hide the node in the Joliet tree, if Joliet extension are enabled */ |
|
LIBISO_HIDE_ON_JOLIET = 1 << 1, |
|
/** Hide the node in the ISO-9660:1999 tree, if that format is enabled */ |
|
LIBISO_HIDE_ON_1999 = 1 << 2, |
|
|
|
/** Hide the node in the HFS+ tree, if that format is enabled. |
|
@since 1.2.4 |
|
*/ |
|
LIBISO_HIDE_ON_HFSPLUS = 1 << 4, |
|
|
|
/** Hide the node in the FAT tree, if that format is enabled. |
|
@since 1.2.4 |
|
*/ |
|
LIBISO_HIDE_ON_FAT = 1 << 5, |
|
|
|
/** With IsoNode and IsoBoot: Write data content even if the node is |
|
* not visible in any tree. |
|
* With directory nodes : Write data content of IsoNode and IsoBoot |
|
* in the directory's tree unless they are |
|
* explicitely marked LIBISO_HIDE_ON_RR |
|
* without LIBISO_HIDE_BUT_WRITE. |
|
* @since 0.6.34 |
|
*/ |
|
LIBISO_HIDE_BUT_WRITE = 1 << 3 |
|
}; |
|
|
|
/** |
|
* El-Torito bootable image type. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
enum eltorito_boot_media_type { |
|
ELTORITO_FLOPPY_EMUL, |
|
ELTORITO_HARD_DISC_EMUL, |
|
ELTORITO_NO_EMUL |
|
}; |
|
|
|
/** |
|
* Replace mode used when addding a node to a directory. |
|
* This controls how libisofs will act when you tried to add to a dir a file |
|
* with the same name that an existing file. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
enum iso_replace_mode { |
|
/** |
|
* Never replace an existing node, and instead fail with |
|
* ISO_NODE_NAME_NOT_UNIQUE. |
|
*/ |
|
ISO_REPLACE_NEVER, |
|
/** |
|
* Always replace the old node with the new. |
|
*/ |
|
ISO_REPLACE_ALWAYS, |
|
/** |
|
* Replace with the new node if it is the same file type |
|
*/ |
|
ISO_REPLACE_IF_SAME_TYPE, |
|
/** |
|
* Replace with the new node if it is the same file type and its ctime |
|
* is newer than the old one. |
|
*/ |
|
ISO_REPLACE_IF_SAME_TYPE_AND_NEWER, |
|
/** |
|
* Replace with the new node if its ctime is newer than the old one. |
|
*/ |
|
ISO_REPLACE_IF_NEWER |
|
/* |
|
* TODO #00006 define more values |
|
* -if both are dirs, add contents (and what to do with conflicts?) |
|
*/ |
|
}; |
|
|
|
/** |
|
* Options for image written. |
|
* @see iso_write_opts_new() |
|
* @since 0.6.2 |
|
*/ |
|
typedef struct iso_write_opts IsoWriteOpts; |
|
|
|
/** |
|
* Options for image reading or import. |
|
* @see iso_read_opts_new() |
|
* @since 0.6.2 |
|
*/ |
|
typedef struct iso_read_opts IsoReadOpts; |
|
|
|
/** |
|
* Source for image reading. |
|
* |
|
* @see struct iso_data_source |
|
* @since 0.6.2 |
|
*/ |
|
typedef struct iso_data_source IsoDataSource; |
|
|
|
/** |
|
* Data source used by libisofs for reading an existing image. |
|
* |
|
* It offers homogeneous read access to arbitrary blocks to different sources |
|
* for images, such as .iso files, CD/DVD drives, etc... |
|
* |
|
* To create a multisession image, libisofs needs a IsoDataSource, that the |
|
* user must provide. The function iso_data_source_new_from_file() constructs |
|
* an IsoDataSource that uses POSIX I/O functions to access data. You can use |
|
* it with regular .iso images, and also with block devices that represent a |
|
* drive. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
struct iso_data_source |
|
{ |
|
|
|
/* reserved for future usage, set to 0 */ |
|
int version; |
|
|
|
/** |
|
* Reference count for the data source. Should be 1 when a new source |
|
* is created. Don't access it directly, but with iso_data_source_ref() |
|
* and iso_data_source_unref() functions. |
|
*/ |
|
unsigned int refcount; |
|
|
|
/** |
|
* Opens the given source. You must open() the source before any attempt |
|
* to read data from it. The open is the right place for grabbing the |
|
* underlying resources. |
|
* |
|
* @return |
|
* 1 if success, < 0 on error (has to be a valid libisofs error code) |
|
*/ |
|
int (*open)(IsoDataSource *src); |
|
|
|
/** |
|
* Close a given source, freeing all system resources previously grabbed in |
|
* open(). |
|
* |
|
* @return |
|
* 1 if success, < 0 on error (has to be a valid libisofs error code) |
|
*/ |
|
int (*close)(IsoDataSource *src); |
|
|
|
/** |
|
* Read an arbitrary block (2048 bytes) of data from the source. |
|
* |
|
* @param lba |
|
* Block to be read. |
|
* @param buffer |
|
* Buffer where the data will be written. It should have at least |
|
* 2048 bytes. |
|
* @return |
|
* 1 if success, |
|
* < 0 if error. This function has to emit a valid libisofs error code. |
|
* Predifined (but not mandatory) for this purpose are: |
|
* ISO_DATA_SOURCE_SORRY , ISO_DATA_SOURCE_MISHAP, |
|
* ISO_DATA_SOURCE_FAILURE , ISO_DATA_SOURCE_FATAL |
|
*/ |
|
int (*read_block)(IsoDataSource *src, uint32_t lba, uint8_t *buffer); |
|
|
|
/** |
|
* Clean up the source specific data. Never call this directly, it is |
|
* automatically called by iso_data_source_unref() when refcount reach |
|
* 0. |
|
*/ |
|
void (*free_data)(IsoDataSource *src); |
|
|
|
/** Source specific data */ |
|
void *data; |
|
}; |
|
|
|
/** |
|
* Return information for image. This is optionally allocated by libisofs, |
|
* as a way to inform user about the features of an existing image, such as |
|
* extensions present, size, ... |
|
* |
|
* @see iso_image_import() |
|
* @since 0.6.2 |
|
*/ |
|
typedef struct iso_read_image_features IsoReadImageFeatures; |
|
|
|
/** |
|
* POSIX abstraction for source files. |
|
* |
|
* @see struct iso_file_source |
|
* @since 0.6.2 |
|
*/ |
|
typedef struct iso_file_source IsoFileSource; |
|
|
|
/** |
|
* Abstract for source filesystems. |
|
* |
|
* @see struct iso_filesystem |
|
* @since 0.6.2 |
|
*/ |
|
typedef struct iso_filesystem IsoFilesystem; |
|
|
|
/** |
|
* Interface that defines the operations (methods) available for an |
|
* IsoFileSource. |
|
* |
|
* @see struct IsoFileSource_Iface |
|
* @since 0.6.2 |
|
*/ |
|
typedef struct IsoFileSource_Iface IsoFileSourceIface; |
|
|
|
/** |
|
* IsoFilesystem implementation to deal with ISO images, and to offer a way to |
|
* access specific information of the image, such as several volume attributes, |
|
* extensions being used, El-Torito artifacts... |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
typedef IsoFilesystem IsoImageFilesystem; |
|
|
|
/** |
|
* See IsoFilesystem->get_id() for info about this. |
|
* @since 0.6.2 |
|
*/ |
|
extern unsigned int iso_fs_global_id; |
|
|
|
/** |
|
* An IsoFilesystem is a handler for a source of files, or a "filesystem". |
|
* That is defined as a set of files that are organized in a hierarchical |
|
* structure. |
|
* |
|
* A filesystem allows libisofs to access files from several sources in |
|
* an homogeneous way, thus abstracting the underlying operations needed to |
|
* access and read file contents. Note that this doesn't need to be tied |
|
* to the disc filesystem used in the partition being accessed. For example, |
|
* we have an IsoFilesystem implementation to access any mounted filesystem, |
|
* using standard POSIX functions. It is also legal, of course, to implement |
|
* an IsoFilesystem to deal with a specific filesystem over raw partitions. |
|
* That is what we do, for example, to access an ISO Image. |
|
* |
|
* Each file inside an IsoFilesystem is represented as an IsoFileSource object, |
|
* that defines POSIX-like interface for accessing files. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
struct iso_filesystem |
|
{ |
|
/** |
|
* Type of filesystem. |
|
* "file" -> local filesystem |
|
* "iso " -> iso image filesystem |
|
*/ |
|
char type[4]; |
|
|
|
/* reserved for future usage, set to 0 */ |
|
int version; |
|
|
|
/** |
|
* Get the root of a filesystem. |
|
* |
|
* @return |
|
* 1 on success, < 0 on error (has to be a valid libisofs error code) |
|
*/ |
|
int (*get_root)(IsoFilesystem *fs, IsoFileSource **root); |
|
|
|
/** |
|
* Retrieve a file from its absolute path inside the filesystem. |
|
* @param file |
|
* Returns a pointer to a IsoFileSource object representing the |
|
* file. It has to be disposed by iso_file_source_unref() when |
|
* no longer needed. |
|
* @return |
|
* 1 success, < 0 error (has to be a valid libisofs error code) |
|
* Error codes: |
|
* ISO_FILE_ACCESS_DENIED |
|
* ISO_FILE_BAD_PATH |
|
* ISO_FILE_DOESNT_EXIST |
|
* ISO_OUT_OF_MEM |
|
* ISO_FILE_ERROR |
|
* ISO_NULL_POINTER |
|
*/ |
|
int (*get_by_path)(IsoFilesystem *fs, const char *path, |
|
IsoFileSource **file); |
|
|
|
/** |
|
* Get filesystem identifier. |
|
* |
|
* If the filesystem is able to generate correct values of the st_dev |
|
* and st_ino fields for the struct stat of each file, this should |
|
* return an unique number, greater than 0. |
|
* |
|
* To get a identifier for your filesystem implementation you should |
|
* use iso_fs_global_id, incrementing it by one each time. |
|
* |
|
* Otherwise, if you can't ensure values in the struct stat are valid, |
|
* this should return 0. |
|
*/ |
|
unsigned int (*get_id)(IsoFilesystem *fs); |
|
|
|
/** |
|
* Opens the filesystem for several read operations. Calling this funcion |
|
* is not needed at all, each time that the underlying system resource |
|
* needs to be accessed, it is openned propertly. |
|
* However, if you plan to execute several operations on the filesystem, |
|
* it is a good idea to open it previously, to prevent several open/close |
|
* operations to occur. |
|
* |
|
* @return 1 on success, < 0 on error (has to be a valid libisofs error code) |
|
*/ |
|
int (*open)(IsoFilesystem *fs); |
|
|
|
/** |
|
* Close the filesystem, thus freeing all system resources. You should |
|
* call this function if you have previously open() it. |
|
* Note that you can open()/close() a filesystem several times. |
|
* |
|
* @return 1 on success, < 0 on error (has to be a valid libisofs error code) |
|
*/ |
|
int (*close)(IsoFilesystem *fs); |
|
|
|
/** |
|
* Free implementation specific data. Should never be called by user. |
|
* Use iso_filesystem_unref() instead. |
|
*/ |
|
void (*free)(IsoFilesystem *fs); |
|
|
|
/* internal usage, do never access them directly */ |
|
unsigned int refcount; |
|
void *data; |
|
}; |
|
|
|
/** |
|
* Interface definition for an IsoFileSource. Defines the POSIX-like function |
|
* to access files and abstract underlying source. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
struct IsoFileSource_Iface |
|
{ |
|
/** |
|
* Tells the version of the interface: |
|
* Version 0 provides functions up to (*lseek)(). |
|
* @since 0.6.2 |
|
* Version 1 additionally provides function *(get_aa_string)(). |
|
* @since 0.6.14 |
|
* Version 2 additionally provides function *(clone_src)(). |
|
* @since 1.0.2 |
|
*/ |
|
int version; |
|
|
|
/** |
|
* Get the absolute path in the filesystem this file source belongs to. |
|
* |
|
* @return |
|
* the path of the FileSource inside the filesystem, it should be |
|
* freed when no more needed. |
|
*/ |
|
char* (*get_path)(IsoFileSource *src); |
|
|
|
/** |
|
* Get the name of the file, with the dir component of the path. |
|
* |
|
* @return |
|
* the name of the file, it should be freed when no more needed. |
|
*/ |
|
char* (*get_name)(IsoFileSource *src); |
|
|
|
/** |
|
* Get information about the file. It is equivalent to lstat(2). |
|
* |
|
* @return |
|
* 1 success, < 0 error (has to be a valid libisofs error code) |
|
* Error codes: |
|
* ISO_FILE_ACCESS_DENIED |
|
* ISO_FILE_BAD_PATH |
|
* ISO_FILE_DOESNT_EXIST |
|
* ISO_OUT_OF_MEM |
|
* ISO_FILE_ERROR |
|
* ISO_NULL_POINTER |
|
*/ |
|
int (*lstat)(IsoFileSource *src, struct stat *info); |
|
|
|
/** |
|
* Get information about the file. If the file is a symlink, the info |
|
* returned refers to the destination. It is equivalent to stat(2). |
|
* |
|
* @return |
|
* 1 success, < 0 error |
|
* Error codes: |
|
* ISO_FILE_ACCESS_DENIED |
|
* ISO_FILE_BAD_PATH |
|
* ISO_FILE_DOESNT_EXIST |
|
* ISO_OUT_OF_MEM |
|
* ISO_FILE_ERROR |
|
* ISO_NULL_POINTER |
|
*/ |
|
int (*stat)(IsoFileSource *src, struct stat *info); |
|
|
|
/** |
|
* Check if the process has access to read file contents. Note that this |
|
* is not necessarily related with (l)stat functions. For example, in a |
|
* filesystem implementation to deal with an ISO image, if the user has |
|
* read access to the image it will be able to read all files inside it, |
|
* despite of the particular permission of each file in the RR tree, that |
|
* are what the above functions return. |
|
* |
|
* @return |
|
* 1 if process has read access, < 0 on error (has to be a valid |
|
* libisofs error code) |
|
* Error codes: |
|
* ISO_FILE_ACCESS_DENIED |
|
* ISO_FILE_BAD_PATH |
|
* ISO_FILE_DOESNT_EXIST |
|
* ISO_OUT_OF_MEM |
|
* ISO_FILE_ERROR |
|
* ISO_NULL_POINTER |
|
*/ |
|
int (*access)(IsoFileSource *src); |
|
|
|
/** |
|
* Opens the source. |
|
* @return 1 on success, < 0 on error (has to be a valid libisofs error code) |
|
* Error codes: |
|
* ISO_FILE_ALREADY_OPENED |
|
* ISO_FILE_ACCESS_DENIED |
|
* ISO_FILE_BAD_PATH |
|
* ISO_FILE_DOESNT_EXIST |
|
* ISO_OUT_OF_MEM |
|
* ISO_FILE_ERROR |
|
* ISO_NULL_POINTER |
|
*/ |
|
int (*open)(IsoFileSource *src); |
|
|
|
/** |
|
* Close a previuously openned file |
|
* @return 1 on success, < 0 on error |
|
* Error codes: |
|
* ISO_FILE_ERROR |
|
* ISO_NULL_POINTER |
|
* ISO_FILE_NOT_OPENED |
|
*/ |
|
int (*close)(IsoFileSource *src); |
|
|
|
/** |
|
* Attempts to read up to count bytes from the given source into |
|
* the buffer starting at buf. |
|
* |
|
* The file src must be open() before calling this, and close() when no |
|
* more needed. Not valid for dirs. On symlinks it reads the destination |
|
* file. |
|
* |
|
* @return |
|
* number of bytes read, 0 if EOF, < 0 on error (has to be a valid |
|
* libisofs error code) |
|
* Error codes: |
|
* ISO_FILE_ERROR |
|
* ISO_NULL_POINTER |
|
* ISO_FILE_NOT_OPENED |
|
* ISO_WRONG_ARG_VALUE -> if count == 0 |
|
* ISO_FILE_IS_DIR |
|
* ISO_OUT_OF_MEM |
|
* ISO_INTERRUPTED |
|
*/ |
|
int (*read)(IsoFileSource *src, void *buf, size_t count); |
|
|
|
/** |
|
* Read a directory. |
|
* |
|
* Each call to this function will return a new children, until we reach |
|
* the end of file (i.e, no more children), in that case it returns 0. |
|
* |
|
* The dir must be open() before calling this, and close() when no more |
|
* needed. Only valid for dirs. |
|
* |
|
* Note that "." and ".." children MUST NOT BE returned. |
|
* |
|
* @param child |
|
* pointer to be filled with the given child. Undefined on error or OEF |
|
* @return |
|
* 1 on success, 0 if EOF (no more children), < 0 on error (has to be |
|
* a valid libisofs error code) |
|
* Error codes: |
|
* ISO_FILE_ERROR |
|
* ISO_NULL_POINTER |
|
* ISO_FILE_NOT_OPENED |
|
* ISO_FILE_IS_NOT_DIR |
|
* ISO_OUT_OF_MEM |
|
*/ |
|
int (*readdir)(IsoFileSource *src, IsoFileSource **child); |
|
|
|
/** |
|
* Read the destination of a symlink. You don't need to open the file |
|
* to call this. |
|
* |
|
* @param buf |
|
* allocated buffer of at least bufsiz bytes. |
|
* The dest. will be copied there, and it will be NULL-terminated |
|
* @param bufsiz |
|
* characters to be copied. Destination link will be truncated if |
|
* it is larger than given size. This include the 0x0 character. |
|
* @return |
|
* 1 on success, < 0 on error (has to be a valid libisofs error code) |
|
* Error codes: |
|
* ISO_FILE_ERROR |
|
* ISO_NULL_POINTER |
|
* ISO_WRONG_ARG_VALUE -> if bufsiz <= 0 |
|
* ISO_FILE_IS_NOT_SYMLINK |
|
* ISO_OUT_OF_MEM |
|
* ISO_FILE_BAD_PATH |
|
* ISO_FILE_DOESNT_EXIST |
|
* |
|
*/ |
|
int (*readlink)(IsoFileSource *src, char *buf, size_t bufsiz); |
|
|
|
/** |
|
* Get the filesystem for this source. No extra ref is added, so you |
|
* musn't unref the IsoFilesystem. |
|
* |
|
* @return |
|
* The filesystem, NULL on error |
|
*/ |
|
IsoFilesystem* (*get_filesystem)(IsoFileSource *src); |
|
|
|
/** |
|
* Free implementation specific data. Should never be called by user. |
|
* Use iso_file_source_unref() instead. |
|
*/ |
|
void (*free)(IsoFileSource *src); |
|
|
|
/** |
|
* Repositions the offset of the IsoFileSource (must be opened) to the |
|
* given offset according to the value of flag. |
|
* |
|
* @param offset |
|
* in bytes |
|
* @param flag |
|
* 0 The offset is set to offset bytes (SEEK_SET) |
|
* 1 The offset is set to its current location plus offset bytes |
|
* (SEEK_CUR) |
|
* 2 The offset is set to the size of the file plus offset bytes |
|
* (SEEK_END). |
|
* @return |
|
* Absolute offset position of the file, or < 0 on error. Cast the |
|
* returning value to int to get a valid libisofs error. |
|
* |
|
* @since 0.6.4 |
|
*/ |
|
off_t (*lseek)(IsoFileSource *src, off_t offset, int flag); |
|
|
|
/* Add-ons of .version 1 begin here */ |
|
|
|
/** |
|
* Valid only if .version is > 0. See above. |
|
* Get the AAIP string with encoded ACL and xattr. |
|
* (Not to be confused with ECMA-119 Extended Attributes). |
|
* |
|
* bit1 and bit2 of flag should be implemented so that freshly fetched |
|
* info does not include the undesired ACL or xattr. Nevertheless if the |
|
* aa_string is cached, then it is permissible that ACL and xattr are still |
|
* delivered. |
|
* |
|
* @param flag Bitfield for control purposes |
|
* bit0= Transfer ownership of AAIP string data. |
|
* src will free the eventual cached data and might |
|
* not be able to produce it again. |
|
* bit1= No need to get ACL (no guarantee of exclusion) |
|
* bit2= No need to get xattr (no guarantee of exclusion) |
|
* @param aa_string Returns a pointer to the AAIP string data. If no AAIP |
|
* string is available, *aa_string becomes NULL. |
|
* (See doc/susp_aaip_*_*.txt for the meaning of AAIP and |
|
* libisofs/aaip_0_2.h for encoding and decoding.) |
|
* The caller is responsible for finally calling free() |
|
* on non-NULL results. |
|
* @return 1 means success (*aa_string == NULL is possible) |
|
* <0 means failure and must b a valid libisofs error code |
|
* (e.g. ISO_FILE_ERROR if no better one can be found). |
|
* @since 0.6.14 |
|
*/ |
|
int (*get_aa_string)(IsoFileSource *src, |
|
unsigned char **aa_string, int flag); |
|
|
|
/** |
|
* Produce a copy of a source. It must be possible to operate both source |
|
* objects concurrently. |
|
* |
|
* @param old_src |
|
* The existing source object to be copied |
|
* @param new_stream |
|
* Will return a pointer to the copy |
|
* @param flag |
|
* Bitfield for control purposes. Submit 0 for now. |
|
* The function shall return ISO_STREAM_NO_CLONE on unknown flag bits. |
|
* |
|
* @since 1.0.2 |
|
* Present if .version is 2 or higher. |
|
*/ |
|
int (*clone_src)(IsoFileSource *old_src, IsoFileSource **new_src, |
|
int flag); |
|
|
|
/* |
|
* TODO #00004 Add a get_mime_type() function. |
|
* This can be useful for GUI apps, to choose the icon of the file |
|
*/ |
|
}; |
|
|
|
#ifndef __cplusplus |
|
#ifndef Libisofs_h_as_cpluspluS |
|
|
|
/** |
|
* An IsoFile Source is a POSIX abstraction of a file. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
struct iso_file_source |
|
{ |
|
const IsoFileSourceIface *class; |
|
int refcount; |
|
void *data; |
|
}; |
|
|
|
#endif /* ! Libisofs_h_as_cpluspluS */ |
|
#endif /* ! __cplusplus */ |
|
|
|
|
|
/* A class of IsoStream is implemented by a class description |
|
* IsoStreamIface = struct IsoStream_Iface |
|
* and a structure of data storage for each instance of IsoStream. |
|
* This structure shall be known to the functions of the IsoStreamIface. |
|
* To create a custom IsoStream class: |
|
* - Define the structure of the custom instance data. |
|
* - Implement the methods which are described by the definition of |
|
* struct IsoStream_Iface (see below), |
|
* - Create a static instance of IsoStreamIface which lists the methods as |
|
* C function pointers. (Example in libisofs/stream.c : fsrc_stream_class) |
|
* To create an instance of that class: |
|
* - Allocate sizeof(IsoStream) bytes of memory and initialize it as |
|
* struct iso_stream : |
|
* - Point to the custom IsoStreamIface by member .class . |
|
* - Set member .refcount to 1. |
|
* - Let member .data point to the custom instance data. |
|
* |
|
* Regrettably the choice of the structure member name "class" makes it |
|
* impossible to implement this generic interface in C++ language directly. |
|
* If C++ is absolutely necessary then you will have to make own copies |
|
* of the public API structures. Use other names but take care to maintain |
|
* the same memory layout. |
|
*/ |
|
|
|
/** |
|
* Representation of file contents. It is an stream of bytes, functionally |
|
* like a pipe. |
|
* |
|
* @since 0.6.4 |
|
*/ |
|
typedef struct iso_stream IsoStream; |
|
|
|
/** |
|
* Interface that defines the operations (methods) available for an |
|
* IsoStream. |
|
* |
|
* @see struct IsoStream_Iface |
|
* @since 0.6.4 |
|
*/ |
|
typedef struct IsoStream_Iface IsoStreamIface; |
|
|
|
/** |
|
* Serial number to be used when you can't get a valid id for a Stream by other |
|
* means. If you use this, both fs_id and dev_id should be set to 0. |
|
* This must be incremented each time you get a reference to it. |
|
* |
|
* @see IsoStreamIface->get_id() |
|
* @since 0.6.4 |
|
*/ |
|
extern ino_t serial_id; |
|
|
|
/** |
|
* Interface definition for IsoStream methods. It is public to allow |
|
* implementation of own stream types. |
|
* The methods defined here typically make use of stream.data which points |
|
* to the individual state data of stream instances. |
|
* |
|
* @since 0.6.4 |
|
*/ |
|
|
|
struct IsoStream_Iface |
|
{ |
|
/* |
|
* Current version of the interface. |
|
* Version 0 (since 0.6.4) |
|
* deprecated but still valid. |
|
* Version 1 (since 0.6.8) |
|
* update_size() added. |
|
* Version 2 (since 0.6.18) |
|
* get_input_stream() added. |
|
* A filter stream must have version 2 at least. |
|
* Version 3 (since 0.6.20) |
|
* cmp_ino() added. |
|
* A filter stream should have version 3 at least. |
|
* Version 4 (since 1.0.2) |
|
* clone_stream() added. |
|
*/ |
|
int version; |
|
|
|
/** |
|
* Type of Stream. |
|
* "fsrc" -> Read from file source |
|
* "cout" -> Cut out interval from disk file |
|
* "mem " -> Read from memory |
|
* "boot" -> Boot catalog |
|
* "extf" -> External filter program |
|
* "ziso" -> zisofs compression |
|
* "osiz" -> zisofs uncompression |
|
* "gzip" -> gzip compression |
|
* "pizg" -> gzip uncompression (gunzip) |
|
* "user" -> User supplied stream |
|
*/ |
|
char type[4]; |
|
|
|
/** |
|
* Opens the stream. |
|
* |
|
* @return |
|
* 1 on success, 2 file greater than expected, 3 file smaller than |
|
* expected, < 0 on error (has to be a valid libisofs error code) |
|
*/ |
|
int (*open)(IsoStream *stream); |
|
|
|
/** |
|
* Close the Stream. |
|
* @return |
|
* 1 on success, < 0 on error (has to be a valid libisofs error code) |
|
*/ |
|
int (*close)(IsoStream *stream); |
|
|
|
/** |
|
* Get the size (in bytes) of the stream. This function should always |
|
* return the same size, even if the underlying source size changes, |
|
* unless you call update_size() method. |
|
*/ |
|
off_t (*get_size)(IsoStream *stream); |
|
|
|
/** |
|
* Attempt to read up to count bytes from the given stream into |
|
* the buffer starting at buf. The implementation has to make sure that |
|
* either the full desired count of bytes is delivered or that the |
|
* next call to this function will return EOF or error. |
|
* I.e. only the last read block may be shorter than parameter count. |
|
* |
|
* The stream must be open() before calling this, and close() when no |
|
* more needed. |
|
* |
|
* @return |
|
* number of bytes read, 0 if EOF, < 0 on error (has to be a valid |
|
* libisofs error code) |
|
*/ |
|
int (*read)(IsoStream *stream, void *buf, size_t count); |
|
|
|
/** |
|
* Tell whether this IsoStream can be read several times, with the same |
|
* results. For example, a regular file is repeatable, you can read it |
|
* as many times as you want. However, a pipe is not. |
|
* |
|
* @return |
|
* 1 if stream is repeatable, 0 if not, |
|
* < 0 on error (has to be a valid libisofs error code) |
|
*/ |
|
int (*is_repeatable)(IsoStream *stream); |
|
|
|
/** |
|
* Get an unique identifier for the IsoStream. |
|
*/ |
|
void (*get_id)(IsoStream *stream, unsigned int *fs_id, dev_t *dev_id, |
|
ino_t *ino_id); |
|
|
|
/** |
|
* Free implementation specific data. Should never be called by user. |
|
* Use iso_stream_unref() instead. |
|
*/ |
|
void (*free)(IsoStream *stream); |
|
|
|
/** |
|
* Update the size of the IsoStream with the current size of the underlying |
|
* source, if the source is prone to size changes. After calling this, |
|
* get_size() shall eventually return the new size. |
|
* This will never be called after iso_image_create_burn_source() was |
|
* called and before the image was completely written. |
|
* (The API call to update the size of all files in the image is |
|
* iso_image_update_sizes()). |
|
* |
|
* @return |
|
* 1 if ok, < 0 on error (has to be a valid libisofs error code) |
|
* |
|
* @since 0.6.8 |
|
* Present if .version is 1 or higher. |
|
*/ |
|
int (*update_size)(IsoStream *stream); |
|
|
|
/** |
|
* Retrieve the eventual input stream of a filter stream. |
|
* |
|
* @param stream |
|
* The eventual filter stream to be inquired. |
|
* @param flag |
|
* Bitfield for control purposes. 0 means normal behavior. |
|
* @return |
|
* The input stream, if one exists. Elsewise NULL. |
|
* No extra reference to the stream shall be taken by this call. |
|
* |
|
* @since 0.6.18 |
|
* Present if .version is 2 or higher. |
|
*/ |
|
IsoStream *(*get_input_stream)(IsoStream *stream, int flag); |
|
|
|
/** |
|
* Compare two streams whether they are based on the same input and will |
|
* produce the same output. If in any doubt, then this comparison should |
|
* indicate no match. A match might allow hardlinking of IsoFile objects. |
|
* |
|
* A pointer value of NULL is permissible. In this case, function |
|
* iso_stream_cmp_ino() will decide on its own. |
|
* |
|
* If not NULL, this function .cmp_ino() will be called by |
|
* iso_stream_cmp_ino() if both compared streams point to it, and if not |
|
* flag bit0 of iso_stream_cmp_ino() prevents it. |
|
* So a .cmp_ino() function must be able to compare any pair of streams |
|
* which name it as their .cmp_ino(). A fallback to iso_stream_cmp_ino(,,1) |
|
* would endanger transitivity of iso_stream_cmp_ino(,,0). |
|
* |
|
* With filter streams, the decision whether the underlying chains of |
|
* streams match, should be delegated to |
|
* iso_stream_cmp_ino(iso_stream_get_input_stream(s1, 0), |
|
* iso_stream_get_input_stream(s2, 0), 0); |
|
* |
|
* The stream.cmp_ino() function has to establish an equivalence and order |
|
* relation: |
|
* cmp_ino(A,A) == 0 |
|
* cmp_ino(A,B) == -cmp_ino(B,A) |
|
* if cmp_ino(A,B) == 0 && cmp_ino(B,C) == 0 then cmp_ino(A,C) == 0 |
|
* Most tricky is the demand for transitivity: |
|
* if cmp_ino(A,B) < 0 && cmp_ino(B,C) < 0 then cmp_ino(A,C) < 0 |
|
* |
|
* @param s1 |
|
* The first stream to compare. Expect foreign stream types. |
|
* @param s2 |
|
* The second stream to compare. Expect foreign stream types. |
|
* @return |
|
* -1 if s1 is smaller s2 , 0 if s1 matches s2 , 1 if s1 is larger s2 |
|
* |
|
* @since 0.6.20 |
|
* Present if .version is 3 or higher. |
|
*/ |
|
int (*cmp_ino)(IsoStream *s1, IsoStream *s2); |
|
|
|
/** |
|
* Produce a copy of a stream. It must be possible to operate both stream |
|
* objects concurrently. |
|
* |
|
* @param old_stream |
|
* The existing stream object to be copied |
|
* @param new_stream |
|
* Will return a pointer to the copy |
|
* @param flag |
|
* Bitfield for control purposes. 0 means normal behavior. |
|
* The function shall return ISO_STREAM_NO_CLONE on unknown flag bits. |
|
* @return |
|
* 1 in case of success, or an error code < 0 |
|
* |
|
* @since 1.0.2 |
|
* Present if .version is 4 or higher. |
|
*/ |
|
int (*clone_stream)(IsoStream *old_stream, IsoStream **new_stream, |
|
int flag); |
|
|
|
}; |
|
|
|
#ifndef __cplusplus |
|
#ifndef Libisofs_h_as_cpluspluS |
|
|
|
/** |
|
* Representation of file contents as a stream of bytes. |
|
* |
|
* @since 0.6.4 |
|
*/ |
|
struct iso_stream |
|
{ |
|
IsoStreamIface *class; |
|
int refcount; |
|
void *data; |
|
}; |
|
|
|
#endif /* ! Libisofs_h_as_cpluspluS */ |
|
#endif /* ! __cplusplus */ |
|
|
|
|
|
/** |
|
* Initialize libisofs. Before any usage of the library you must either call |
|
* this function or iso_init_with_flag(). |
|
* Only exception from this rule: iso_lib_version(), iso_lib_is_compatible(). |
|
* @return 1 on success, < 0 on error |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_init(); |
|
|
|
/** |
|
* Initialize libisofs. Before any usage of the library you must either call |
|
* this function or iso_init() which is equivalent to iso_init_with_flag(0). |
|
* Only exception from this rule: iso_lib_version(), iso_lib_is_compatible(). |
|
* @param flag |
|
* Bitfield for control purposes |
|
* bit0= do not set up locale by LC_* environment variables |
|
* @return 1 on success, < 0 on error |
|
* |
|
* @since 0.6.18 |
|
*/ |
|
int iso_init_with_flag(int flag); |
|
|
|
/** |
|
* Finalize libisofs. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
void iso_finish(); |
|
|
|
/** |
|
* Override the reply of libc function nl_langinfo(CODESET) which may or may |
|
* not give the name of the character set which is in effect for your |
|
* environment. So this call can compensate for inconsistent terminal setups. |
|
* Another use case is to choose UTF-8 as intermediate character set for a |
|
* conversion from an exotic input character set to an exotic output set. |
|
* |
|
* @param name |
|
* Name of the character set to be assumed as "local" one. |
|
* @param flag |
|
* Unused yet. Submit 0. |
|
* @return |
|
* 1 indicates success, <=0 failure |
|
* |
|
* @since 0.6.12 |
|
*/ |
|
int iso_set_local_charset(char *name, int flag); |
|
|
|
/** |
|
* Obtain the local charset as currently assumed by libisofs. |
|
* The result points to internal memory. It is volatile and must not be |
|
* altered. |
|
* |
|
* @param flag |
|
* Unused yet. Submit 0. |
|
* |
|
* @since 0.6.12 |
|
*/ |
|
char *iso_get_local_charset(int flag); |
|
|
|
/** |
|
* Create a new image, empty. |
|
* |
|
* The image will be owned by you and should be unref() when no more needed. |
|
* |
|
* @param name |
|
* Name of the image. This will be used as volset_id and volume_id. |
|
* @param image |
|
* Location where the image pointer will be stored. |
|
* @return |
|
* 1 success, < 0 error |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_image_new(const char *name, IsoImage **image); |
|
|
|
|
|
/** |
|
* Control whether ACL and xattr will be imported from external filesystems |
|
* (typically the local POSIX filesystem) when new nodes get inserted. If |
|
* enabled by iso_write_opts_set_aaip() they will later be written into the |
|
* image as AAIP extension fields. |
|
* |
|
* A change of this setting does neither affect existing IsoNode objects |
|
* nor the way how ACL and xattr are handled when loading an ISO image. |
|
* The latter is controlled by iso_read_opts_set_no_aaip(). |
|
* |
|
* @param image |
|
* The image of which the behavior is to be controlled |
|
* @param what |
|
* A bit field which sets the behavior: |
|
* bit0= ignore ACLs if the external file object bears some |
|
* bit1= ignore xattr if the external file object bears some |
|
* all other bits are reserved |
|
* |
|
* @since 0.6.14 |
|
*/ |
|
void iso_image_set_ignore_aclea(IsoImage *image, int what); |
|
|
|
|
|
/** |
|
* Creates an IsoWriteOpts for writing an image. You should set the options |
|
* desired with the correspondent setters. |
|
* |
|
* Options by default are determined by the selected profile. Fifo size is set |
|
* by default to 2 MB. |
|
* |
|
* @param opts |
|
* Pointer to the location where the newly created IsoWriteOpts will be |
|
* stored. You should free it with iso_write_opts_free() when no more |
|
* needed. |
|
* @param profile |
|
* Default profile for image creation. For now the following values are |
|
* defined: |
|
* ---> 0 [BASIC] |
|
* No extensions are enabled, and ISO level is set to 1. Only suitable |
|
* for usage for very old and limited systems (like MS-DOS), or by a |
|
* start point from which to set your custom options. |
|
* ---> 1 [BACKUP] |
|
* POSIX compatibility for backup. Simple settings, ISO level is set to |
|
* 3 and RR extensions are enabled. Useful for backup purposes. |
|
* Note that ACL and xattr are not enabled by default. |
|
* If you enable them, expect them not to show up in the mounted image. |
|
* They will have to be retrieved by libisofs applications like xorriso. |
|
* ---> 2 [DISTRIBUTION] |
|
* Setting for information distribution. Both RR and Joliet are enabled |
|
* to maximize compatibility with most systems. Permissions are set to |
|
* default values, and timestamps to the time of recording. |
|
* @return |
|
* 1 success, < 0 error |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_new(IsoWriteOpts **opts, int profile); |
|
|
|
/** |
|
* Free an IsoWriteOpts previously allocated with iso_write_opts_new(). |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
void iso_write_opts_free(IsoWriteOpts *opts); |
|
|
|
/** |
|
* Announce that only the image size is desired, that the struct burn_source |
|
* which is set to consume the image output stream will stay inactive, |
|
* and that the write thread will be cancelled anyway by the .cancel() method |
|
* of the struct burn_source. |
|
* This avoids to create a write thread which would begin production of the |
|
* image stream and would generate a MISHAP event when burn_source.cancel() |
|
* gets into effect. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param will_cancel |
|
* 0= normal image generation |
|
* 1= prepare for being canceled before image stream output is completed |
|
* @return |
|
* 1 success, < 0 error |
|
* |
|
* @since 0.6.40 |
|
*/ |
|
int iso_write_opts_set_will_cancel(IsoWriteOpts *opts, int will_cancel); |
|
|
|
/** |
|
* Set the ISO-9960 level to write at. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param level |
|
* -> 1 for higher compatibility with old systems. With this level |
|
* filenames are restricted to 8.3 characters. |
|
* -> 2 to allow up to 31 filename characters. |
|
* -> 3 to allow files greater than 4GB |
|
* @return |
|
* 1 success, < 0 error |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_iso_level(IsoWriteOpts *opts, int level); |
|
|
|
/** |
|
* Whether to use or not Rock Ridge extensions. |
|
* |
|
* This are standard extensions to ECMA-119, intended to add POSIX filesystem |
|
* features to ECMA-119 images. Thus, usage of this flag is highly recommended |
|
* for images used on GNU/Linux systems. With the usage of RR extension, the |
|
* resulting image will have long filenames (up to 255 characters), deeper |
|
* directory structure, POSIX permissions and owner info on files and |
|
* directories, support for symbolic links or special files... All that |
|
* attributes can be modified/set with the appropriate function. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param enable |
|
* 1 to enable RR extension, 0 to not add them |
|
* @return |
|
* 1 success, < 0 error |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_rockridge(IsoWriteOpts *opts, int enable); |
|
|
|
/** |
|
* Whether to add the non-standard Joliet extension to the image. |
|
* |
|
* This extensions are heavily used in Microsoft Windows systems, so if you |
|
* plan to use your disc on such a system you should add this extension. |
|
* Usage of Joliet supplies longer filesystem length (up to 64 unicode |
|
* characters), and deeper directory structure. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param enable |
|
* 1 to enable Joliet extension, 0 to not add them |
|
* @return |
|
* 1 success, < 0 error |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_joliet(IsoWriteOpts *opts, int enable); |
|
|
|
/** |
|
* Whether to add a HFS+ filesystem to the image which points to the same |
|
* file content as the other directory trees. |
|
* It will get marked by an Apple Partition Map in the System Area of the ISO |
|
* image. This may collide with data submitted by |
|
* iso_write_opts_set_system_area() |
|
* and with settings made by |
|
* el_torito_set_isolinux_options() |
|
* The first 8 bytes of the System Area get overwritten by |
|
* {0x45, 0x52, 0x08 0x00, 0xeb, 0x02, 0xff, 0xff} |
|
* which can be executed as x86 machine code without negative effects. |
|
* So if an MBR gets combined with this feature, then its first 8 bytes |
|
* should contain no essential commands. |
|
* The next blocks of 2 KiB in the System Area will be occupied by APM entries. |
|
* The first one covers the part of the ISO image before the HFS+ filesystem |
|
* metadata. The second one marks the range from HFS+ metadata to the end |
|
* of file content data. If more ISO image data follow, then a third partition |
|
* entry gets produced. Other features of libisofs might cause the need for |
|
* more APM entries. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param enable |
|
* 1 to enable HFS+ extension, 0 to not add HFS+ metadata and APM |
|
* @return |
|
* 1 success, < 0 error |
|
* |
|
* @since 1.2.4 |
|
*/ |
|
int iso_write_opts_set_hfsplus(IsoWriteOpts *opts, int enable); |
|
|
|
/** |
|
* >>> Production of FAT32 is not implemented yet. |
|
* >>> This call exists only as preparation for implementation. |
|
* |
|
* Whether to add a FAT32 filesystem to the image which points to the same |
|
* file content as the other directory trees. |
|
* |
|
* >>> FAT32 is planned to get implemented in co-existence with HFS+ |
|
* >>> Describe impact on MBR |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param enable |
|
* 1 to enable FAT32 extension, 0 to not add FAT metadata |
|
* @return |
|
* 1 success, < 0 error |
|
* |
|
* @since 1.2.4 |
|
*/ |
|
int iso_write_opts_set_fat(IsoWriteOpts *opts, int enable); |
|
|
|
/** |
|
* Supply a serial number for the HFS+ extension of the emerging image. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param serial_number |
|
* 8 bytes which should be unique to the image. |
|
* If all bytes are 0, then the serial number will be generated as |
|
* random number by libisofs. This is the default setting. |
|
* @return |
|
* 1 success, < 0 error |
|
* |
|
* @since 1.2.4 |
|
*/ |
|
int iso_write_opts_set_hfsp_serial_number(IsoWriteOpts *opts, |
|
uint8_t serial_number[8]); |
|
|
|
/** |
|
* Set the block size for Apple Partition Map and for HFS+. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param hfsp_block_size |
|
* The allocation block size to be used by the HFS+ fileystem. |
|
* 0, 512, or 2048 |
|
* @param apm_block_size |
|
* The block size to be used for and within the Apple Partition Map. |
|
* 0, 512, or 2048. |
|
* Size 512 is not compatible with options which produce GPT. |
|
* @return |
|
* 1 success, < 0 error |
|
* |
|
* @since 1.2.4 |
|
*/ |
|
int iso_write_opts_set_hfsp_block_size(IsoWriteOpts *opts, |
|
int hfsp_block_size, int apm_block_size); |
|
|
|
|
|
/** |
|
* Whether to use newer ISO-9660:1999 version. |
|
* |
|
* This is the second version of ISO-9660. It allows longer filenames and has |
|
* less restrictions than old ISO-9660. However, nobody is using it so there |
|
* are no much reasons to enable this. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_iso1999(IsoWriteOpts *opts, int enable); |
|
|
|
/** |
|
* Control generation of non-unique inode numbers for the emerging image. |
|
* Inode numbers get written as "file serial number" with PX entries as of |
|
* RRIP-1.12. They may mark families of hardlinks. |
|
* RRIP-1.10 prescribes a PX entry without file serial number. If not overriden |
|
* by iso_write_opts_set_rrip_1_10_px_ino() there will be no file serial number |
|
* written into RRIP-1.10 images. |
|
* |
|
* Inode number generation does not affect IsoNode objects which imported their |
|
* inode numbers from the old ISO image (see iso_read_opts_set_new_inos()) |
|
* and which have not been altered since import. It rather applies to IsoNode |
|
* objects which were newly added to the image, or to IsoNode which brought no |
|
* inode number from the old image, or to IsoNode where certain properties |
|
* have been altered since image import. |
|
* |
|
* If two IsoNode are found with same imported inode number but differing |
|
* properties, then one of them will get assigned a new unique inode number. |
|
* I.e. the hardlink relation between both IsoNode objects ends. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param enable |
|
* 1 = Collect IsoNode objects which have identical data sources and |
|
* properties. |
|
* 0 = Generate unique inode numbers for all IsoNode objects which do not |
|
* have a valid inode number from an imported ISO image. |
|
* All other values are reserved. |
|
* |
|
* @since 0.6.20 |
|
*/ |
|
int iso_write_opts_set_hardlinks(IsoWriteOpts *opts, int enable); |
|
|
|
/** |
|
* Control writing of AAIP informations for ACL and xattr. |
|
* For importing ACL and xattr when inserting nodes from external filesystems |
|
* (e.g. the local POSIX filesystem) see iso_image_set_ignore_aclea(). |
|
* For loading of this information from images see iso_read_opts_set_no_aaip(). |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param enable |
|
* 1 = write AAIP information from nodes into the image |
|
* 0 = do not write AAIP information into the image |
|
* All other values are reserved. |
|
* |
|
* @since 0.6.14 |
|
*/ |
|
int iso_write_opts_set_aaip(IsoWriteOpts *opts, int enable); |
|
|
|
/** |
|
* Use this only if you need to reproduce a suboptimal behavior of older |
|
* versions of libisofs. They used address 0 for links and device files, |
|
* and the address of the Volume Descriptor Set Terminator for empty data |
|
* files. |
|
* New versions let symbolic links, device files, and empty data files point |
|
* to a dedicated block of zero-bytes after the end of the directory trees. |
|
* (Single-pass reader libarchive needs to see all directory info before |
|
* processing any data files.) |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param enable |
|
* 1 = use the suboptimal block addresses in the range of 0 to 115. |
|
* 0 = use the address of a block after the directory tree. (Default) |
|
* |
|
* @since 1.0.2 |
|
*/ |
|
int iso_write_opts_set_old_empty(IsoWriteOpts *opts, int enable); |
|
|
|
/** |
|
* Caution: This option breaks any assumptions about names that |
|
* are supported by ECMA-119 specifications. |
|
* Try to omit any translation which would make a file name compliant to the |
|
* ECMA-119 rules. This includes and exceeds omit_version_numbers, |
|
* max_37_char_filenames, no_force_dots bit0, allow_full_ascii. Further it |
|
* prevents the conversion from local character set to ASCII. |
|
* The maximum name length is given by this call. If a filename exceeds |
|
* this length or cannot be recorded untranslated for other reasons, then |
|
* image production is aborted with ISO_NAME_NEEDS_TRANSL. |
|
* Currently the length limit is 96 characters, because an ECMA-119 directory |
|
* record may at most have 254 bytes and up to 158 other bytes must fit into |
|
* the record. Probably 96 more bytes can be made free for the name in future. |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param len |
|
* 0 = disable this feature and perform name translation according to |
|
* other settings. |
|
* >0 = Omit any translation. Eventually abort image production |
|
* if a name is longer than the given value. |
|
* -1 = Like >0. Allow maximum possible length (currently 96) |
|
* @return >=0 success, <0 failure |
|
* In case of >=0 the return value tells the effectively set len. |
|
* E.g. 96 after using len == -1. |
|
* @since 1.0.0 |
|
*/ |
|
int iso_write_opts_set_untranslated_name_len(IsoWriteOpts *opts, int len); |
|
|
|
/** |
|
* Convert directory names for ECMA-119 similar to other file names, but do |
|
* not force a dot or add a version number. |
|
* This violates ECMA-119 by allowing one "." and especially ISO level 1 |
|
* by allowing DOS style 8.3 names rather than only 8 characters. |
|
* (mkisofs and its clones seem to do this violation.) |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param allow |
|
* 1= allow dots , 0= disallow dots and convert them |
|
* @return |
|
* 1 success, < 0 error |
|
* @since 1.0.0 |
|
*/ |
|
int iso_write_opts_set_allow_dir_id_ext(IsoWriteOpts *opts, int allow); |
|
|
|
/** |
|
* Omit the version number (";1") at the end of the ISO-9660 identifiers. |
|
* This breaks ECMA-119 specification, but version numbers are usually not |
|
* used, so it should work on most systems. Use with caution. |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param omit |
|
* bit0= omit version number with ECMA-119 and Joliet |
|
* bit1= omit version number with Joliet alone (@since 0.6.30) |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_omit_version_numbers(IsoWriteOpts *opts, int omit); |
|
|
|
/** |
|
* Allow ISO-9660 directory hierarchy to be deeper than 8 levels. |
|
* This breaks ECMA-119 specification. Use with caution. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_allow_deep_paths(IsoWriteOpts *opts, int allow); |
|
|
|
/** |
|
* This call describes the directory where to store Rock Ridge relocated |
|
* directories. |
|
* If not iso_write_opts_set_allow_deep_paths(,1) is in effect, then it may |
|
* become necessary to relocate directories so that no ECMA-119 file path |
|
* has more than 8 components. These directories are grafted into either |
|
* the root directory of the ISO image or into a dedicated relocation |
|
* directory. |
|
* For Rock Ridge, the relocated directories are linked forth and back to |
|
* placeholders at their original positions in path level 8. Directories |
|
* marked by Rock Ridge entry RE are to be considered artefacts of relocation |
|
* and shall not be read into a Rock Ridge tree. Instead they are to be read |
|
* via their placeholders and their links. |
|
* For plain ECMA-119, the relocation directory and the relocated directories |
|
* are just normal directories which contain normal files and directories. |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param name |
|
* The name of the relocation directory in the root directory. Do not |
|
* prepend "/". An empty name or NULL will direct relocated directories |
|
* into the root directory. This is the default. |
|
* If the given name does not exist in the root directory when |
|
* iso_image_create_burn_source() is called, and if there are directories |
|
* at path level 8, then directory /name will be created automatically. |
|
* The name given by this call will be compared with iso_node_get_name() |
|
* of the directories in the root directory, not with the final ECMA-119 |
|
* names of those directories. |
|
* @param flags |
|
* Bitfield for control purposes. |
|
* bit0= Mark the relocation directory by a Rock Ridge RE entry, if it |
|
* gets created during iso_image_create_burn_source(). This will |
|
* make it invisible for most Rock Ridge readers. |
|
* bit1= not settable via API (used internally) |
|
* @return |
|
* 1 success, < 0 error |
|
* @since 1.2.2 |
|
*/ |
|
int iso_write_opts_set_rr_reloc(IsoWriteOpts *opts, char *name, int flags); |
|
|
|
/** |
|
* Allow path in the ISO-9660 tree to have more than 255 characters. |
|
* This breaks ECMA-119 specification. Use with caution. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_allow_longer_paths(IsoWriteOpts *opts, int allow); |
|
|
|
/** |
|
* Allow a single file or directory identifier to have up to 37 characters. |
|
* This is larger than the 31 characters allowed by ISO level 2, and the |
|
* extra space is taken from the version number, so this also forces |
|
* omit_version_numbers. |
|
* This breaks ECMA-119 specification and could lead to buffer overflow |
|
* problems on old systems. Use with caution. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_max_37_char_filenames(IsoWriteOpts *opts, int allow); |
|
|
|
/** |
|
* ISO-9660 forces filenames to have a ".", that separates file name from |
|
* extension. libisofs adds it if original filename doesn't has one. Set |
|
* this to 1 to prevent this behavior. |
|
* This breaks ECMA-119 specification. Use with caution. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param no |
|
* bit0= no forced dot with ECMA-119 |
|
* bit1= no forced dot with Joliet (@since 0.6.30) |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_no_force_dots(IsoWriteOpts *opts, int no); |
|
|
|
/** |
|
* Allow lowercase characters in ISO-9660 filenames. By default, only |
|
* uppercase characters, numbers and a few other characters are allowed. |
|
* This breaks ECMA-119 specification. Use with caution. |
|
* If lowercase is not allowed then those letters get mapped to uppercase |
|
* letters. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_allow_lowercase(IsoWriteOpts *opts, int allow); |
|
|
|
/** |
|
* Allow all 8-bit characters to appear on an ISO-9660 filename. Note |
|
* that "/" and 0x0 characters are never allowed, even in RR names. |
|
* This breaks ECMA-119 specification. Use with caution. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_allow_full_ascii(IsoWriteOpts *opts, int allow); |
|
|
|
/** |
|
* If not iso_write_opts_set_allow_full_ascii() is set to 1: |
|
* Allow all 7-bit characters that would be allowed by allow_full_ascii, but |
|
* map lowercase to uppercase if iso_write_opts_set_allow_lowercase() |
|
* is not set to 1. |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param allow |
|
* If not zero, then allow what is described above. |
|
* |
|
* @since 1.2.2 |
|
*/ |
|
int iso_write_opts_set_allow_7bit_ascii(IsoWriteOpts *opts, int allow); |
|
|
|
/** |
|
* Allow all characters to be part of Volume and Volset identifiers on |
|
* the Primary Volume Descriptor. This breaks ISO-9660 contraints, but |
|
* should work on modern systems. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_relaxed_vol_atts(IsoWriteOpts *opts, int allow); |
|
|
|
/** |
|
* Allow paths in the Joliet tree to have more than 240 characters. |
|
* This breaks Joliet specification. Use with caution. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_joliet_longer_paths(IsoWriteOpts *opts, int allow); |
|
|
|
/** |
|
* Allow leaf names in the Joliet tree to have up to 103 characters. |
|
* Normal limit is 64. |
|
* This breaks Joliet specification. Use with caution. |
|
* |
|
* @since 1.0.6 |
|
*/ |
|
int iso_write_opts_set_joliet_long_names(IsoWriteOpts *opts, int allow); |
|
|
|
/** |
|
* Use character set UTF-16BE with Joliet, which is a superset of the |
|
* actually prescribed character set UCS-2. |
|
* This breaks Joliet specification with exotic characters which would |
|
* elsewise be mapped to underscore '_'. Use with caution. |
|
* |
|
* @since 1.3.6 |
|
*/ |
|
int iso_write_opts_set_joliet_utf16(IsoWriteOpts *opts, int allow); |
|
|
|
/** |
|
* Write Rock Ridge info as of specification RRIP-1.10 rather than RRIP-1.12: |
|
* signature "RRIP_1991A" rather than "IEEE_1282", field PX without file |
|
* serial number. |
|
* |
|
* @since 0.6.12 |
|
*/ |
|
int iso_write_opts_set_rrip_version_1_10(IsoWriteOpts *opts, int oldvers); |
|
|
|
/** |
|
* Write field PX with file serial number (i.e. inode number) even if |
|
* iso_write_opts_set_rrip_version_1_10(,1) is in effect. |
|
* This clearly violates the RRIP-1.10 specs. But it is done by mkisofs since |
|
* a while and no widespread protest is visible in the web. |
|
* If this option is not enabled, then iso_write_opts_set_hardlinks() will |
|
* only have an effect with iso_write_opts_set_rrip_version_1_10(,0). |
|
* |
|
* @since 0.6.20 |
|
*/ |
|
int iso_write_opts_set_rrip_1_10_px_ino(IsoWriteOpts *opts, int enable); |
|
|
|
/** |
|
* Write AAIP as extension according to SUSP 1.10 rather than SUSP 1.12. |
|
* I.e. without announcing it by an ER field and thus without the need |
|
* to precede the RRIP fields and the AAIP field by ES fields. |
|
* This saves 5 to 10 bytes per file and might avoid problems with readers |
|
* which dislike ER fields other than the ones for RRIP. |
|
* On the other hand, SUSP 1.12 frowns on such unannounced extensions |
|
* and prescribes ER and ES. It does this since the year 1994. |
|
* |
|
* In effect only if above iso_write_opts_set_aaip() enables writing of AAIP. |
|
* |
|
* @since 0.6.14 |
|
*/ |
|
int iso_write_opts_set_aaip_susp_1_10(IsoWriteOpts *opts, int oldvers); |
|
|
|
/** |
|
* Store as ECMA-119 Directory Record timestamp the mtime of the source node |
|
* rather than the image creation time. |
|
* If storing of mtime is enabled, then the settings of |
|
* iso_write_opts_set_replace_timestamps() apply. (replace==1 will revoke, |
|
* replace==2 will override mtime by iso_write_opts_set_default_timestamp(). |
|
* |
|
* Since version 1.2.0 this may apply also to Joliet and ISO 9660:1999. To |
|
* reduce the probability of unwanted behavior changes between pre-1.2.0 and |
|
* post-1.2.0, the bits for Joliet and ISO 9660:1999 also enable ECMA-119. |
|
* The hopefully unlikely bit14 may then be used to disable mtime for ECMA-119. |
|
* |
|
* To enable mtime for all three directory trees, submit 7. |
|
* To disable this feature completely, submit 0. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param allow |
|
* If this parameter is negative, then mtime is enabled only for ECMA-119. |
|
* With positive numbers, the parameter is interpreted as bit field : |
|
* bit0= enable mtime for ECMA-119 |
|
* bit1= enable mtime for Joliet and ECMA-119 |
|
* bit2= enable mtime for ISO 9660:1999 and ECMA-119 |
|
* bit14= disable mtime for ECMA-119 although some of the other bits |
|
* would enable it |
|
* @since 1.2.0 |
|
* Before version 1.2.0 this applied only to ECMA-119 : |
|
* 0 stored image creation time in ECMA-119 tree. |
|
* Any other value caused storing of mtime. |
|
* Joliet and ISO 9660:1999 always stored the image creation time. |
|
* @since 0.6.12 |
|
*/ |
|
int iso_write_opts_set_dir_rec_mtime(IsoWriteOpts *opts, int allow); |
|
|
|
/** |
|
* Whether to sort files based on their weight. |
|
* |
|
* @see iso_node_set_sort_weight |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_sort_files(IsoWriteOpts *opts, int sort); |
|
|
|
/** |
|
* Whether to compute and record MD5 checksums for the whole session and/or |
|
* for each single IsoFile object. The checksums represent the data as they |
|
* were written into the image output stream, not necessarily as they were |
|
* on hard disk at any point of time. |
|
* See also calls iso_image_get_session_md5() and iso_file_get_md5(). |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param session |
|
* If bit0 set: Compute session checksum |
|
* @param files |
|
* If bit0 set: Compute a checksum for each single IsoFile object which |
|
* gets its data content written into the session. Copy |
|
* checksums from files which keep their data in older |
|
* sessions. |
|
* If bit1 set: Check content stability (only with bit0). I.e. before |
|
* writing the file content into to image stream, read it |
|
* once and compute a MD5. Do a second reading for writing |
|
* into the image stream. Afterwards compare both MD5 and |
|
* issue a MISHAP event ISO_MD5_STREAM_CHANGE if they do not |
|
* match. |
|
* Such a mismatch indicates content changes between the |
|
* time point when the first MD5 reading started and the |
|
* time point when the last block was read for writing. |
|
* So there is high risk that the image stream was fed from |
|
* changing and possibly inconsistent file content. |
|
* |
|
* @since 0.6.22 |
|
*/ |
|
int iso_write_opts_set_record_md5(IsoWriteOpts *opts, int session, int files); |
|
|
|
/** |
|
* Set the parameters "name" and "timestamp" for a scdbackup checksum tag. |
|
* It will be appended to the libisofs session tag if the image starts at |
|
* LBA 0 (see iso_write_opts_set_ms_block()). The scdbackup tag can be used |
|
* to verify the image by command scdbackup_verify device -auto_end. |
|
* See scdbackup/README appendix VERIFY for its inner details. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param name |
|
* A word of up to 80 characters. Typically volno_totalno telling |
|
* that this is volume volno of a total of totalno volumes. |
|
* @param timestamp |
|
* A string of 13 characters YYMMDD.hhmmss (e.g. A90831.190324). |
|
* A9 = 2009, B0 = 2010, B1 = 2011, ... C0 = 2020, ... |
|
* @param tag_written |
|
* Either NULL or the address of an array with at least 512 characters. |
|
* In the latter case the eventually produced scdbackup tag will be |
|
* copied to this array when the image gets written. This call sets |
|
* scdbackup_tag_written[0] = 0 to mark its preliminary invalidity. |
|
* @return |
|
* 1 indicates success, <0 is error |
|
* |
|
* @since 0.6.24 |
|
*/ |
|
int iso_write_opts_set_scdbackup_tag(IsoWriteOpts *opts, |
|
char *name, char *timestamp, |
|
char *tag_written); |
|
|
|
/** |
|
* Whether to set default values for files and directory permissions, gid and |
|
* uid. All these take one of three values: 0, 1 or 2. |
|
* |
|
* If 0, the corresponding attribute will be kept as set in the IsoNode. |
|
* Unless you have changed it, it corresponds to the value on disc, so it |
|
* is suitable for backup purposes. If set to 1, the corresponding attrib. |
|
* will be changed by a default suitable value. Finally, if you set it to |
|
* 2, the attrib. will be changed with the value specified by the functioins |
|
* below. Note that for mode attributes, only the permissions are set, the |
|
* file type remains unchanged. |
|
* |
|
* @see iso_write_opts_set_default_dir_mode |
|
* @see iso_write_opts_set_default_file_mode |
|
* @see iso_write_opts_set_default_uid |
|
* @see iso_write_opts_set_default_gid |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_replace_mode(IsoWriteOpts *opts, int dir_mode, |
|
int file_mode, int uid, int gid); |
|
|
|
/** |
|
* Set the mode to use on dirs when you set the replace_mode of dirs to 2. |
|
* |
|
* @see iso_write_opts_set_replace_mode |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_default_dir_mode(IsoWriteOpts *opts, mode_t dir_mode); |
|
|
|
/** |
|
* Set the mode to use on files when you set the replace_mode of files to 2. |
|
* |
|
* @see iso_write_opts_set_replace_mode |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_default_file_mode(IsoWriteOpts *opts, mode_t file_mode); |
|
|
|
/** |
|
* Set the uid to use when you set the replace_uid to 2. |
|
* |
|
* @see iso_write_opts_set_replace_mode |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_default_uid(IsoWriteOpts *opts, uid_t uid); |
|
|
|
/** |
|
* Set the gid to use when you set the replace_gid to 2. |
|
* |
|
* @see iso_write_opts_set_replace_mode |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_default_gid(IsoWriteOpts *opts, gid_t gid); |
|
|
|
/** |
|
* 0 to use IsoNode timestamps, 1 to use recording time, 2 to use |
|
* values from timestamp field. This applies to the timestamps of Rock Ridge |
|
* and if the use of mtime is enabled by iso_write_opts_set_dir_rec_mtime(). |
|
* In the latter case, value 1 will revoke the recording of mtime, value |
|
* 2 will override mtime by iso_write_opts_set_default_timestamp(). |
|
* |
|
* @see iso_write_opts_set_default_timestamp |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_replace_timestamps(IsoWriteOpts *opts, int replace); |
|
|
|
/** |
|
* Set the timestamp to use when you set the replace_timestamps to 2. |
|
* |
|
* @see iso_write_opts_set_replace_timestamps |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_default_timestamp(IsoWriteOpts *opts, time_t timestamp); |
|
|
|
/** |
|
* Whether to always record timestamps in GMT. |
|
* |
|
* By default, libisofs stores local time information on image. You can set |
|
* this to always store timestamps converted to GMT. This prevents any |
|
* discrimination of the timezone of the image preparer by the image reader. |
|
* |
|
* It is useful if you want to hide your timezone, or you live in a timezone |
|
* that can't be represented in ECMA-119. These are timezones with an offset |
|
* from GMT greater than +13 hours, lower than -12 hours, or not a multiple |
|
* of 15 minutes. |
|
* Negative timezones (west of GMT) can trigger bugs in some operating systems |
|
* which typically appear in mounted ISO images as if the timezone shift from |
|
* GMT was applied twice (e.g. in New York 22:36 becomes 17:36). |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_always_gmt(IsoWriteOpts *opts, int gmt); |
|
|
|
/** |
|
* Set the charset to use for the RR names of the files that will be created |
|
* on the image. |
|
* NULL to use default charset, that is the locale charset. |
|
* You can obtain the list of charsets supported on your system executing |
|
* "iconv -l" in a shell. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_output_charset(IsoWriteOpts *opts, const char *charset); |
|
|
|
/** |
|
* Set the type of image creation in case there was already an existing |
|
* image imported. Libisofs supports two types of creation: |
|
* stand-alone and appended. |
|
* |
|
* A stand-alone image is an image that does not need the old image any more |
|
* for being mounted by the operating system or imported by libisofs. It may |
|
* be written beginning with byte 0 of optical media or disk file objects. |
|
* There will be no distinction between files from the old image and those |
|
* which have been added by the new image generation. |
|
* |
|
* On the other side, an appended image is not self contained. It may refer |
|
* to files that stay stored in the imported existing image. |
|
* This usage model is inspired by CD multi-session. It demands that the |
|
* appended image is finally written to the same media or disk file |
|
* as the imported image at an address behind the end of that imported image. |
|
* The exact address may depend on media peculiarities and thus has to be |
|
* announced by the application via iso_write_opts_set_ms_block(). |
|
* The real address where the data will be written is under control of the |
|
* consumer of the struct burn_source which takes the output of libisofs |
|
* image generation. It may be the one announced to libisofs or an intermediate |
|
* one. Nevertheless, the image will be readable only at the announced address. |
|
* |
|
* If you have not imported a previous image by iso_image_import(), then the |
|
* image will always be a stand-alone image, as there is no previous data to |
|
* refer to. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param append |
|
* 1 to create an appended image, 0 for an stand-alone one. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_appendable(IsoWriteOpts *opts, int append); |
|
|
|
/** |
|
* Set the start block of the image. It is supposed to be the lba where the |
|
* first block of the image will be written on disc. All references inside the |
|
* ISO image will take this into account, thus providing a mountable image. |
|
* |
|
* For appendable images, that are written to a new session, you should |
|
* pass here the lba of the next writable address on disc. |
|
* |
|
* In stand alone images this is usually 0. However, you may want to |
|
* provide a different ms_block if you don't plan to burn the image in the |
|
* first session on disc, such as in some CD-Extra disc whether the data |
|
* image is written in a new session after some audio tracks. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_ms_block(IsoWriteOpts *opts, uint32_t ms_block); |
|
|
|
/** |
|
* Sets the buffer where to store the descriptors which shall be written |
|
* at the beginning of an overwriteable media to point to the newly written |
|
* image. |
|
* This is needed if the write start address of the image is not 0. |
|
* In this case the first 64 KiB of the media have to be overwritten |
|
* by the buffer content after the session was written and the buffer |
|
* was updated by libisofs. Otherwise the new session would not be |
|
* found by operating system function mount() or by libisoburn. |
|
* (One could still mount that session if its start address is known.) |
|
* |
|
* If you do not need this information, for example because you are creating a |
|
* new image for LBA 0 or because you will create an image for a true |
|
* multisession media, just do not use this call or set buffer to NULL. |
|
* |
|
* Use cases: |
|
* |
|
* - Together with iso_write_opts_set_appendable(opts, 1) the buffer serves |
|
* for the growing of an image as done in growisofs by Andy Polyakov. |
|
* This allows appending of a new session to non-multisession media, such |
|
* as DVD+RW. The new session will refer to the data of previous sessions |
|
* on the same media. |
|
* libisoburn emulates multisession appendability on overwriteable media |
|
* and disk files by performing this use case. |
|
* |
|
* - Together with iso_write_opts_set_appendable(opts, 0) the buffer allows |
|
* to write the first session on overwriteable media to start addresses |
|
* other than 0. |
|
* This address must not be smaller than 32 blocks plus the eventual |
|
* partition offset as defined by iso_write_opts_set_part_offset(). |
|
* libisoburn in most cases writes the first session on overwriteable media |
|
* and disk files to LBA (32 + partition_offset) in order to preserve its |
|
* descriptors from the subsequent overwriting by the descriptor buffer of |
|
* later sessions. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param overwrite |
|
* When not NULL, it should point to at least 64KiB of memory, where |
|
* libisofs will install the contents that shall be written at the |
|
* beginning of overwriteable media. |
|
* You should initialize the buffer either with 0s, or with the contents |
|
* of the first 32 blocks of the image you are growing. In most cases, |
|
* 0 is good enought. |
|
* IMPORTANT: If you use iso_write_opts_set_part_offset() then the |
|
* overwrite buffer must be larger by the offset defined there. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_overwrite_buf(IsoWriteOpts *opts, uint8_t *overwrite); |
|
|
|
/** |
|
* Set the size, in number of blocks, of the ring buffer used between the |
|
* writer thread and the burn_source. You have to provide at least a 32 |
|
* blocks buffer. Default value is set to 2MB, if that is ok for you, you |
|
* don't need to call this function. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_write_opts_set_fifo_size(IsoWriteOpts *opts, size_t fifo_size); |
|
|
|
/* |
|
* Attach 32 kB of binary data which shall get written to the first 32 kB |
|
* of the ISO image, the ECMA-119 System Area. This space is intended for |
|
* system dependent boot software, e.g. a Master Boot Record which allows to |
|
* boot from USB sticks or hard disks. ECMA-119 makes no own assumptions or |
|
* prescriptions about the byte content. |
|
* |
|
* If system area data are given or options bit0 is set, then bit1 of |
|
* el_torito_set_isolinux_options() is automatically disabled. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param data |
|
* Either NULL or 32 kB of data. Do not submit less bytes ! |
|
* @param options |
|
* Can cause manipulations of submitted data before they get written: |
|
* bit0= Only with System area type 0 = MBR |
|
* Apply a --protective-msdos-label as of grub-mkisofs. |
|
* This means to patch bytes 446 to 512 of the system area so |
|
* that one partition is defined which begins at the second |
|
* 512-byte block of the image and ends where the image ends. |
|
* This works with and without system_area_data. |
|
* Modern GRUB2 system areas get also treated by bit14. See below. |
|
* bit1= Only with System area type 0 = MBR |
|
* Apply isohybrid MBR patching to the system area. |
|
* This works only with system area data from SYSLINUX plus an |
|
* ISOLINUX boot image as first submitted boot image |
|
* (see iso_image_set_boot_image()) and only if not bit0 is set. |
|
* bit2-7= System area type |
|
* 0= with bit0 or bit1: MBR |
|
* else: type depends on bits bit10-13: System area sub type |
|
* 1= MIPS Big Endian Volume Header |
|
* @since 0.6.38 |
|
* Submit up to 15 MIPS Big Endian boot files by |
|
* iso_image_add_mips_boot_file(). |
|
* This will overwrite the first 512 bytes of the submitted |
|
* data. |
|
* 2= DEC Boot Block for MIPS Little Endian |
|
* @since 0.6.38 |
|
* The first boot file submitted by |
|
* iso_image_add_mips_boot_file() will be activated. |
|
* This will overwrite the first 512 bytes of the submitted |
|
* data. |
|
* 3= SUN Disk Label for SUN SPARC |
|
* @since 0.6.40 |
|
* Submit up to 7 SPARC boot images by |
|
* iso_write_opts_set_partition_img() for partition numbers 2 |
|
* to 8. |
|
* This will overwrite the first 512 bytes of the submitted |
|
* data. |
|
* 4= HP-PA PALO boot sector version 4 for HP PA-RISC |
|
* @since 1.3.8 |
|
* Suitable for older PALO of e.g. Debian 4 and 5. |
|
* Submit all five parameters of iso_image_set_hppa_palo(): |
|
* cmdline, bootloader, kernel_32, kernel_64, ramdisk |
|
* 5= HP-PA PALO boot sector version 5 for HP PA-RISC |
|
* @since 1.3.8 |
|
* Suitable for newer PALO, where PALOHDRVERSION in |
|
* lib/common.h is defined as 5. |
|
* Submit all five parameters of iso_image_set_hppa_palo(): |
|
* cmdline, bootloader, kernel_32, kernel_64, ramdisk |
|
* 6= DEC Alpha SRM boot sector |
|
* @since 1.4.0 |
|
* Submit bootloader path in ISO by iso_image_set_alpha_boot(). |
|
* bit8-9= Only with System area type 0 = MBR |
|
* @since 1.0.4 |
|
* Cylinder alignment mode eventually pads the image to make it |
|
* end at a cylinder boundary. |
|
* 0 = auto (align if bit1) |
|
* 1 = always align to cylinder boundary |
|
* 2 = never align to cylinder boundary |
|
* 3 = always align, additionally pad up and align partitions |
|
* which were appended by iso_write_opts_set_partition_img() |
|
* @since 1.2.6 |
|
* bit10-13= System area sub type |
|
* @since 1.2.4 |
|
* With type 0: |
|
* if options bit0 ... MBR with partition start at block 1 |
|
* if options bit1 ... ISOLINUX isohybrid MBR |
|
* else: |
|
* 0 = no particular sub type, use unaltered |
|
* 1 = CHRP: A single MBR partition of type 0x96 covers the |
|
* ISO image. Not compatible with any other feature |
|
* which needs to have own MBR partition entries. |
|
* 2 = generic MBR @since 1.3.8 |
|
* bit14= Only with System area type 0 = MBR |
|
* GRUB2 boot provisions: |
|
* @since 1.3.0 |
|
* Patch system area at byte 0x1b0 to 0x1b7 with |
|
* (512-block address + 4) of the first boot image file. |
|
* Little-endian 8-byte. |
|
* Is normally combined with options bit0. |
|
* Will not be in effect if options bit1 is set. |
|
* bit15= Only with System area type MBR but not with CHRP |
|
* Enforce MBR "bootable/active" flag. In worst case by dummy |
|
* partition of type 0x00 which occupies block 0. |
|
* @since 1.4.4 |
|
* @param flag |
|
* bit0 = invalidate any attached system area data. Same as data == NULL |
|
* (This re-activates eventually loaded image System Area data. |
|
* To erase those, submit 32 kB of zeros without flag bit0.) |
|
* bit1 = keep data unaltered |
|
* bit2 = keep options unaltered |
|
* @return |
|
* ISO_SUCCESS or error |
|
* @since 0.6.30 |
|
*/ |
|
int iso_write_opts_set_system_area(IsoWriteOpts *opts, char data[32768], |
|
int options, int flag); |
|
|
|
/** |
|
* Set a name for the system area. This setting is ignored unless system area |
|
* type 3 "SUN Disk Label" is in effect by iso_write_opts_set_system_area(). |
|
* In this case it will replace the default text at the start of the image: |
|
* "CD-ROM Disc with Sun sparc boot created by libisofs" |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param label |
|
* A text of up to 128 characters. |
|
* @return |
|
* ISO_SUCCESS or error |
|
* @since 0.6.40 |
|
*/ |
|
int iso_write_opts_set_disc_label(IsoWriteOpts *opts, char *label); |
|
|
|
/** |
|
* Explicitely set the four timestamps of the emerging Primary Volume |
|
* Descriptor and in the volume descriptors of Joliet and ISO 9660:1999, |
|
* if those are to be generated. |
|
* Default with all parameters is 0. |
|
* |
|
* ECMA-119 defines them as: |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param vol_creation_time |
|
* When "the information in the volume was created." |
|
* A value of 0 means that the timepoint of write start is to be used. |
|
* @param vol_modification_time |
|
* When "the information in the volume was last modified." |
|
* A value of 0 means that the timepoint of write start is to be used. |
|
* @param vol_expiration_time |
|
* When "the information in the volume may be regarded as obsolete." |
|
* A value of 0 means that the information never shall expire. |
|
* @param vol_effective_time |
|
* When "the information in the volume may be used." |
|
* A value of 0 means that not such retention is intended. |
|
* @param vol_uuid |
|
* If this text is not empty, then it overrides vol_creation_time and |
|
* vol_modification_time by copying the first 16 decimal digits from |
|
* uuid, eventually padding up with decimal '1', and writing a NUL-byte |
|
* as timezone. |
|
* Other than with vol_*_time the resulting string in the ISO image |
|
* is fully predictable and free of timezone pitfalls. |
|
* It should express a reasonable time in form YYYYMMDDhhmmsscc. |
|
* The timezone will always be recorded as GMT. |
|
* E.g.: "2010040711405800" = 7 Apr 2010 11:40:58 (+0 centiseconds) |
|
* @return |
|
* ISO_SUCCESS or error |
|
* |
|
* @since 0.6.30 |
|
*/ |
|
int iso_write_opts_set_pvd_times(IsoWriteOpts *opts, |
|
time_t vol_creation_time, time_t vol_modification_time, |
|
time_t vol_expiration_time, time_t vol_effective_time, |
|
char *vol_uuid); |
|
|
|
|
|
/* |
|
* Control production of a second set of volume descriptors (superblock) |
|
* and directory trees, together with a partition table in the MBR where the |
|
* first partition has non-zero start address and the others are zeroed. |
|
* The first partition stretches to the end of the whole ISO image. |
|
* The additional volume descriptor set and trees will allow to mount the |
|
* ISO image at the start of the first partition, while it is still possible |
|
* to mount it via the normal first volume descriptor set and tree at the |
|
* start of the image or storage device. |
|
* This makes few sense on optical media. But on USB sticks it creates a |
|
* conventional partition table which makes it mountable on e.g. Linux via |
|
* /dev/sdb and /dev/sdb1 alike. |
|
* IMPORTANT: When submitting memory by iso_write_opts_set_overwrite_buf() |
|
* then its size must be at least 64 KiB + partition offset. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param block_offset_2k |
|
* The offset of the partition start relative to device start. |
|
* This is counted in 2 kB blocks. The partition table will show the |
|
* according number of 512 byte sectors. |
|
* Default is 0 which causes no special partition table preparations. |
|
* If it is not 0 then it must not be smaller than 16. |
|
* @param secs_512_per_head |
|
* Number of 512 byte sectors per head. 1 to 63. 0=automatic. |
|
* @param heads_per_cyl |
|
* Number of heads per cylinder. 1 to 255. 0=automatic. |
|
* @return |
|
* ISO_SUCCESS or error |
|
* |
|
* @since 0.6.36 |
|
*/ |
|
int iso_write_opts_set_part_offset(IsoWriteOpts *opts, |
|
uint32_t block_offset_2k, |
|
int secs_512_per_head, int heads_per_cyl); |
|
|
|
|
|
/** The minimum version of libjte to be used with this version of libisofs |
|
at compile time. The use of libjte is optional and depends on configure |
|
tests. It can be prevented by ./configure option --disable-libjte . |
|
@since 0.6.38 |
|
*/ |
|
#define iso_libjte_req_major 1 |
|
#define iso_libjte_req_minor 0 |
|
#define iso_libjte_req_micro 0 |
|
|
|
/** |
|
* Associate a libjte environment object to the upcoming write run. |
|
* libjte implements Jigdo Template Extraction as of Steve McIntyre and |
|
* Richard Atterer. |
|
* The call will fail if no libjte support was enabled at compile time. |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param libjte_handle |
|
* Pointer to a struct libjte_env e.g. created by libjte_new(). |
|
* It must stay existent from the start of image generation by |
|
* iso_image_create_burn_source() until the write thread has ended. |
|
* This can be inquired by iso_image_generator_is_running(). |
|
* In order to keep the libisofs API identical with and without |
|
* libjte support the parameter type is (void *). |
|
* @return |
|
* ISO_SUCCESS or error |
|
* |
|
* @since 0.6.38 |
|
*/ |
|
int iso_write_opts_attach_jte(IsoWriteOpts *opts, void *libjte_handle); |
|
|
|
/** |
|
* Remove eventual association to a libjte environment handle. |
|
* The call will fail if no libjte support was enabled at compile time. |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param libjte_handle |
|
* If not submitted as NULL, this will return the previously set |
|
* libjte handle. |
|
* @return |
|
* ISO_SUCCESS or error |
|
* |
|
* @since 0.6.38 |
|
*/ |
|
int iso_write_opts_detach_jte(IsoWriteOpts *opts, void **libjte_handle); |
|
|
|
|
|
/** |
|
* Cause a number of blocks with zero bytes to be written after the payload |
|
* data, but before the eventual checksum data. Unlike libburn tail padding, |
|
* these blocks are counted as part of the image and covered by eventual |
|
* image checksums. |
|
* A reason for such padding can be the wish to prevent the Linux read-ahead |
|
* bug by sacrificial data which still belong to image and Jigdo template. |
|
* Normally such padding would be the job of the burn program which should know |
|
* that it is needed with CD write type TAO if Linux read(2) shall be able |
|
* to read all payload blocks. |
|
* 150 blocks = 300 kB is the traditional sacrifice to the Linux kernel. |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param num_blocks |
|
* Number of extra 2 kB blocks to be written. |
|
* @return |
|
* ISO_SUCCESS or error |
|
* |
|
* @since 0.6.38 |
|
*/ |
|
int iso_write_opts_set_tail_blocks(IsoWriteOpts *opts, uint32_t num_blocks); |
|
|
|
|
|
/** |
|
* The libisofs interval reader is used internally and offered by libisofs API: |
|
* @since 1.4.0 |
|
* The functions iso_write_opts_set_prep_img(), iso_write_opts_set_efi_bootp(), |
|
* and iso_write_opts_set_partition_img() accept with their flag bit0 an |
|
* interval reader description string instead of a disk path. |
|
* The API calls are iso_interval_reader_new(), iso_interval_reader_read(), |
|
* and iso_interval_reader_destroy(). |
|
* The data may be cut out and optionally partly zeroized. |
|
* |
|
* An interval reader description string has the form: |
|
* $flags:$interval:$zeroizers:$source |
|
* The component $flags modifies the further interpretation: |
|
* "local_fs" ....... demands to read from a file depicted by the path in |
|
* $source. |
|
* "imported_iso" ... demands to read from the IsoDataSource object that was |
|
* used with iso_image_import() when |
|
* iso_read_opts_keep_import_src() was enabled. |
|
* The text in $source is ignored. |
|
* The application has to ensure that reading from the |
|
* import source does not disturb production of the new |
|
* ISO session. Especially this would be the case if the |
|
* import source is the same libburn drive with a |
|
* sequential optical medium to which the new session shall |
|
* get burned. |
|
* The component $interval consists of two byte address numbers separated |
|
* by a "-" character. E.g. "0-429" means to read bytes 0 to 429. |
|
* The component $zeroizers consists of zero or more comma separated strings. |
|
* They define which part of the read data to zeroize. Byte number 0 means |
|
* the byte read from the $interval start address. |
|
* Each string may be either |
|
* "zero_mbrpt" ..... demands to zeroize bytes 446 to 509 of the read data if |
|
* bytes 510 and 511 bear the MBR signature 0x55 0xaa. |
|
* "zero_gpt" ....... demands to check for a GPT header in bytes 512 to 1023, |
|
* to zeroize it and its partition table blocks. |
|
* "zero_apm" ....... demands to check for an APM block 0 and to zeroize |
|
* its partition table blocks. But not the block 0 itself, |
|
* because it could be actually MBR x86 machine code. |
|
* $zero_start"-"$zero_end ... demands to zeroize the read-in bytes beginning |
|
* with number $zero_start and ending after $zero_end. |
|
* The component $source is the file path with "local_fs", and ignored with |
|
* "imported_iso". |
|
* Byte numbers may be scaled by a suffix out of {k,m,g,t,s,d} meaning |
|
* multiplication by {1024, 1024k, 1024m, 1024g, 2048, 512}. A scaled value |
|
* as end number depicts the last byte of the scaled range. |
|
* E.g. "0d-0d" is "0-511". |
|
* Examples: |
|
* "local_fs:0-32767:zero_mbrpt,zero_gpt,440-443:/tmp/template.iso" |
|
* "imported_iso:45056d-47103d::" |
|
*/ |
|
struct iso_interval_reader; |
|
|
|
/** |
|
* Create an interval reader object. |
|
* |
|
* @param img |
|
* The IsoImage object which can provide the "imported_iso" data source. |
|
* @param path |
|
* The interval reader description string. See above. |
|
* @param ivr |
|
* Returns in case of success a pointer to the created object. |
|
* Dispose it by iso_interval_reader_destroy() when no longer needed. |
|
* @param byte_count |
|
* Returns in case of success the number of bytes in the interval. |
|
* @param flag |
|
* bit0= tolerate (src == NULL) with "imported_iso". |
|
* (Will immediately cause eof of interval input.) |
|
* @return |
|
* ISO_SUCCESS or error (which is < 0) |
|
* |
|
* @since 1.4.0 |
|
*/ |
|
int iso_interval_reader_new(IsoImage *img, char *path, |
|
struct iso_interval_reader **ivr, |
|
off_t *byte_count, int flag); |
|
|
|
/** |
|
* Dispose an interval reader object. |
|
* |
|
* @param ivr |
|
* The reader object to be disposed. *ivr will be set to NULL. |
|
* @param flag |
|
* Unused yet. Submit 0. |
|
* @return |
|
* ISO_SUCCESS or error (which is < 0) |
|
* |
|
* @since 1.4.0 |
|
*/ |
|
int iso_interval_reader_destroy(struct iso_interval_reader **ivr, int flag); |
|
|
|
/** |
|
* Read the next block of 2048 bytes from an interval reader object. |
|
* If end-of-input happens, the interval will get filled up with 0 bytes. |
|
* |
|
* @param ivr |
|
* The object to read from. |
|
* @param buf |
|
* Pointer to memory for filling in at least 2048 bytes. |
|
* @param buf_fill |
|
* Will in case of success return the number of valid bytes. |
|
* If this is smaller than 2048, then end-of-interval has occurred. |
|
* @param flag |
|
* Unused yet. Submit 0. |
|
* @return |
|
* ISO_SUCCESS if data were read, 0 if not, < 0 if error |
|
* |
|
* @since 1.4.0 |
|
*/ |
|
int iso_interval_reader_read(struct iso_interval_reader *ivr, uint8_t *buf, |
|
int *buf_fill, int flag); |
|
|
|
|
|
/** |
|
* Copy a data file from the local filesystem into the emerging ISO image. |
|
* Mark it by an MBR partition entry as PreP partition and also cause |
|
* protective MBR partition entries before and after this partition. |
|
* Vladimir Serbinenko stated aboy PreP = PowerPC Reference Platform : |
|
* "PreP [...] refers mainly to IBM hardware. PreP boot is a partition |
|
* containing only raw ELF and having type 0x41." |
|
* |
|
* This feature is only combinable with system area type 0 |
|
* and currently not combinable with ISOLINUX isohybrid production. |
|
* It overrides --protective-msdos-label. See iso_write_opts_set_system_area(). |
|
* Only partition 4 stays available for iso_write_opts_set_partition_img(). |
|
* It is compatible with HFS+/FAT production by storing the PreP partition |
|
* before the start of the HFS+/FAT partition. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param image_path |
|
* File address in the local file system or instructions for interval |
|
* reader. See flag bit0. |
|
* NULL revokes production of the PreP partition. |
|
* @param flag |
|
* bit0= The path contains instructions for the interval reader. |
|
* See above. |
|
* @since 1.4.0 |
|
* All other bits are reserved for future usage. Set them to 0. |
|
* @return |
|
* ISO_SUCCESS or error |
|
* |
|
* @since 1.2.4 |
|
*/ |
|
int iso_write_opts_set_prep_img(IsoWriteOpts *opts, char *image_path, |
|
int flag); |
|
|
|
/** |
|
* Copy a data file from the local filesystem into the emerging ISO image. |
|
* Mark it by an GPT partition entry as EFI System partition, and also cause |
|
* protective GPT partition entries before and after the partition. |
|
* GPT = Globally Unique Identifier Partition Table |
|
* |
|
* This feature may collide with data submitted by |
|
* iso_write_opts_set_system_area() |
|
* and with settings made by |
|
* el_torito_set_isolinux_options() |
|
* It is compatible with HFS+/FAT production by storing the EFI partition |
|
* before the start of the HFS+/FAT partition. |
|
* The GPT overwrites byte 0x0200 to 0x03ff of the system area and all |
|
* further bytes above 0x0800 which are not used by an Apple Partition Map. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param image_path |
|
* File address in the local file system or instructions for interval |
|
* reader. See flag bit0. |
|
* NULL revokes production of the EFI boot partition. |
|
* @param flag |
|
* bit0= The path contains instructions for the interval reader |
|
* See above. |
|
* @since 1.4.0 |
|
* All other bits are reserved for future usage. Set them to 0. |
|
* @return |
|
* ISO_SUCCESS or error |
|
* |
|
* @since 1.2.4 |
|
*/ |
|
int iso_write_opts_set_efi_bootp(IsoWriteOpts *opts, char *image_path, |
|
int flag); |
|
|
|
/** |
|
* Control whether the emerging GPT gets a pseudo-randomly generated disk GUID |
|
* or whether it gets a user supplied GUID. |
|
* The partition GUIDs will be generated in a reproducible way by exoring the |
|
* little-endian 32 bit partion number with the disk GUID beginning at byte |
|
* offset 9. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param guid |
|
* 16 bytes of user supplied GUID. Readily byte-swapped as prescribed by |
|
* UEFI specs: 4 byte, 2 byte, 2 byte as little-endian. The rest as |
|
* big-endian. |
|
* The upper 4 bit of guid[7] should bear the value 4 to express the |
|
* RFC 4122 version 4. Bit 7 of byte[8] should be set to 1 and bit 6 |
|
* be set to 0, in order to express the RFC 4122 variant of UUID, |
|
* where version 4 means "pseudo-random uuid". |
|
* @param mode |
|
* 0 = ignore parameter guid and produce the GPT disk GUID by a |
|
* pseudo-random algorithm. This is the default setting. |
|
* 1 = use parameter guid as GPT disk GUID |
|
* 2 = ignore parameter guid and derive the GPT disk GUID from |
|
* parameter vol_uuid of iso_write_opts_set_pvd_times(). |
|
* The 16 bytes of vol_uuid get copied and bytes 7, 8 get their |
|
* upper bits changed to comply to RFC 4122 and UEFI. |
|
* Error ISO_GPT_NO_VOL_UUID will occur if image production begins |
|
* before vol_uuid was set. |
|
* |
|
* @return |
|
* ISO_SUCCESS or ISO_BAD_GPT_GUID_MODE |
|
* |
|
* @since 1.4.6 |
|
*/ |
|
int iso_write_opts_set_gpt_guid(IsoWriteOpts *opts, uint8_t guid[16], |
|
int mode); |
|
|
|
/** |
|
* Generate a pseudo-random GUID suitable for iso_write_opts_set_gpt_guid(). |
|
* |
|
* @param guid |
|
* Will be filled by 16 bytes of generated GUID. |
|
* |
|
* @since 1.4.6 |
|
*/ |
|
void iso_generate_gpt_guid(uint8_t guid[16]); |
|
|
|
/** |
|
* Cause an arbitrary data file to be appended to the ISO image and to be |
|
* described by a partition table entry in an MBR or SUN Disk Label at the |
|
* start of the ISO image. |
|
* The partition entry will bear the size of the image file rounded up to |
|
* the next multiple of 2048 bytes. |
|
* MBR or SUN Disk Label are selected by iso_write_opts_set_system_area() |
|
* system area type: 0 selects MBR partition table. 3 selects a SUN partition |
|
* table with 320 kB start alignment. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param partition_number |
|
* Depicts the partition table entry which shall describe the |
|
* appended image. |
|
* Range with MBR: 1 to 4. 1 will cause the whole ISO image to be |
|
* unclaimable space before partition 1. |
|
* Range with SUN Disk Label: 2 to 8. |
|
* @param partition_type |
|
* The MBR partition type. E.g. FAT12 = 0x01 , FAT16 = 0x06, |
|
* Linux Native Partition = 0x83. See fdisk command L. |
|
* This parameter is ignored with SUN Disk Label. |
|
* @param image_path |
|
* File address in the local file system or instructions for interval |
|
* reader. See flag bit0. |
|
* With SUN Disk Label: an empty name causes the partition to become |
|
* a copy of the next lower partition. |
|
* @param flag |
|
* bit0= The path contains instructions for the interval reader |
|
* See above. |
|
* @since 1.4.0 |
|
* All other bits are reserved for future usage. Set them to 0. |
|
* @return |
|
* ISO_SUCCESS or error |
|
* |
|
* @since 0.6.38 |
|
*/ |
|
int iso_write_opts_set_partition_img(IsoWriteOpts *opts, int partition_number, |
|
uint8_t partition_type, char *image_path, int flag); |
|
|
|
/** |
|
* Control whether partitions created by iso_write_opts_set_partition_img() |
|
* are to be represented in MBR or as GPT partitions. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param gpt |
|
* 0= represent as MBR partition; as GPT only if other GPT partitions |
|
* are present |
|
* 1= represent as GPT partition and cause protective MBR with a single |
|
* partition which covers the whole output data. |
|
* This may fail if other settings demand MBR partitions. |
|
* @return |
|
* ISO_SUCCESS or error |
|
* |
|
* @since 1.4.0 |
|
*/ |
|
int iso_write_opts_set_appended_as_gpt(IsoWriteOpts *opts, int gpt); |
|
|
|
/** |
|
* Control whether partitions created by iso_write_opts_set_partition_img() |
|
* are to be represented in Apple Partition Map. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param apm |
|
* 0= do not represent appended partitions in APM |
|
* 1= represent in APM, even if not |
|
* iso_write_opts_set_part_like_isohybrid() enables it and no |
|
* other APM partitions emerge. |
|
* @return |
|
* ISO_SUCCESS or error |
|
* |
|
* @since 1.4.4 |
|
*/ |
|
int iso_write_opts_set_appended_as_apm(IsoWriteOpts *opts, int apm); |
|
|
|
/** |
|
* Control whether bits 2 to 8 of el_torito_set_isolinux_options() |
|
* shall apply even if not isohybrid MBR patching is enabled (bit1 of |
|
* parameter options of iso_write_opts_set_system_area()): |
|
* - Mentioning of El Torito boot images in GPT. |
|
* - Mentioning of El Torito boot images in APM. |
|
* |
|
* In this case some other behavior from isohybrid processing will apply too: |
|
* - No MBR partition of type 0xee emerges, even if GPT gets produced. |
|
* - Gaps between GPT and APM partitions will not be filled by more partitions. |
|
* |
|
* An extra feature towards isohybrid is enabled: |
|
* - Appended partitions get mentioned in APM if other APM partitions emerge. |
|
* |
|
* @param opts |
|
* The option set to be manipulated. |
|
* @param alike |
|
* 0= Apply the described behavior only with ISOLINUX isohybrid. |
|
* Do not mention appended partitions in APM unless |
|
* iso_write_opts_set_appended_as_apm() is enabled. |
|
* 1= Apply the described behavior even without ISOLINUX isohybrid. |
|
* |
|
* @return |
|
* ISO_SUCCESS or error |
|
* |
|
* @since 1.4.4 |
|
*/ |
|
int iso_write_opts_set_part_like_isohybrid(IsoWriteOpts *opts, int alike); |
|
|
|
|
|
/** |
|
* Inquire the start address of the file data blocks after having used |
|
* IsoWriteOpts with iso_image_create_burn_source(). |
|
* @param opts |
|
* The option set that was used when starting image creation |
|
* @param data_start |
|
* Returns the logical block address if it is already valid |
|
* @param flag |
|
* Reserved for future usage, set to 0. |
|
* @return |
|
* 1 indicates valid data_start, <0 indicates invalid data_start |
|
* |
|
* @since 0.6.16 |
|
*/ |
|
int iso_write_opts_get_data_start(IsoWriteOpts *opts, uint32_t *data_start, |
|
int flag); |
|
|
|
/** |
|
* Update the sizes of all files added to image. |
|
* |
|
* This may be called just before iso_image_create_burn_source() to force |
|
* libisofs to check the file sizes again (they're already checked when added |
|
* to IsoImage). It is useful if you have changed some files after adding then |
|
* to the image. |
|
* |
|
* @return |
|
* 1 on success, < 0 on error |
|
* @since 0.6.8 |
|
*/ |
|
int iso_image_update_sizes(IsoImage *image); |
|
|
|
/** |
|
* Create a burn_source and a thread which immediately begins to generate |
|
* the image. That burn_source can be used with libburn as a data source |
|
* for a track. A copy of its public declaration in libburn.h can be found |
|
* further below in this text. |
|
* |
|
* If image generation shall be aborted by the application program, then |
|
* the .cancel() method of the burn_source must be called to end the |
|
* generation thread: burn_src->cancel(burn_src); |
|
* |
|
* @param image |
|
* The image to write. |
|
* @param opts |
|
* The options for image generation. All needed data will be copied, so |
|
* you can free the given struct once this function returns. |
|
* @param burn_src |
|
* Location where the pointer to the burn_source will be stored |
|
* @return |
|
* 1 on success, < 0 on error |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_image_create_burn_source(IsoImage *image, IsoWriteOpts *opts, |
|
struct burn_source **burn_src); |
|
|
|
/** |
|
* Inquire whether the image generator thread is still at work. As soon as the |
|
* reply is 0, the caller of iso_image_create_burn_source() may assume that |
|
* the image generation has ended. |
|
* Nevertheless there may still be readily formatted output data pending in |
|
* the burn_source or its consumers. So the final delivery of the image has |
|
* also to be checked at the data consumer side,e.g. by burn_drive_get_status() |
|
* in case of libburn as consumer. |
|
* @param image |
|
* The image to inquire. |
|
* @return |
|
* 1 generating of image stream is still in progress |
|
* 0 generating of image stream has ended meanwhile |
|
* |
|
* @since 0.6.38 |
|
*/ |
|
int iso_image_generator_is_running(IsoImage *image); |
|
|
|
/** |
|
* Creates an IsoReadOpts for reading an existent image. You should set the |
|
* options desired with the correspondent setters. Note that you may want to |
|
* set the start block value. |
|
* |
|
* Options by default are determined by the selected profile. |
|
* |
|
* @param opts |
|
* Pointer to the location where the newly created IsoReadOpts will be |
|
* stored. You should free it with iso_read_opts_free() when no more |
|
* needed. |
|
* @param profile |
|
* Default profile for image reading. For now the following values are |
|
* defined: |
|
* ---> 0 [STANDARD] |
|
* Suitable for most situations. Most extension are read. When both |
|
* Joliet and RR extension are present, RR is used. |
|
* AAIP for ACL and xattr is not enabled by default. |
|
* @return |
|
* 1 success, < 0 error |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_read_opts_new(IsoReadOpts **opts, int profile); |
|
|
|
/** |
|
* Free an IsoReadOpts previously allocated with iso_read_opts_new(). |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
void iso_read_opts_free(IsoReadOpts *opts); |
|
|
|
/** |
|
* Set the block where the image begins. It is usually 0, but may be different |
|
* on a multisession disc. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_read_opts_set_start_block(IsoReadOpts *opts, uint32_t block); |
|
|
|
/** |
|
* Do not read Rock Ridge extensions. |
|
* In most cases you don't want to use this. It could be useful if RR info |
|
* is damaged, or if you want to use the Joliet tree. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_read_opts_set_no_rockridge(IsoReadOpts *opts, int norr); |
|
|
|
/** |
|
* Do not read Joliet extensions. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_read_opts_set_no_joliet(IsoReadOpts *opts, int nojoliet); |
|
|
|
/** |
|
* Do not read ISO 9660:1999 enhanced tree |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_read_opts_set_no_iso1999(IsoReadOpts *opts, int noiso1999); |
|
|
|
/** |
|
* Control reading of AAIP informations about ACL and xattr when loading |
|
* existing images. |
|
* For importing ACL and xattr when inserting nodes from external filesystems |
|
* (e.g. the local POSIX filesystem) see iso_image_set_ignore_aclea(). |
|
* For eventual writing of this information see iso_write_opts_set_aaip(). |
|
* |
|
* @param opts |
|
* The option set to be manipulated |
|
* @param noaaip |
|
* 1 = Do not read AAIP information |
|
* 0 = Read AAIP information if available |
|
* All other values are reserved. |
|
* @since 0.6.14 |
|
*/ |
|
int iso_read_opts_set_no_aaip(IsoReadOpts *opts, int noaaip); |
|
|
|
/** |
|
* Control reading of an array of MD5 checksums which is eventually stored |
|
* at the end of a session. See also iso_write_opts_set_record_md5(). |
|
* Important: Loading of the MD5 array will only work if AAIP is enabled |
|
* because its position and layout is recorded in xattr "isofs.ca". |
|
* |
|
* @param opts |
|
* The option set to be manipulated |
|
* @param no_md5 |
|
* 0 = Read MD5 array if available, refuse on non-matching MD5 tags |
|
* 1 = Do not read MD5 checksum array |
|
* 2 = Read MD5 array, but do not check MD5 tags |
|
* @since 1.0.4 |
|
* All other values are reserved. |
|
* |
|
* @since 0.6.22 |
|
*/ |
|
int iso_read_opts_set_no_md5(IsoReadOpts *opts, int no_md5); |
|
|
|
|
|
/** |
|
* Control discarding of eventual inode numbers from existing images. |
|
* Such numbers may come from RRIP 1.12 entries PX. If not discarded they |
|
* get written unchanged when the file object gets written into an ISO image. |
|
* If this inode number is missing with a file in the imported image, |
|
* or if it has been discarded during image reading, then a unique inode number |
|
* will be generated at some time before the file gets written into an ISO |
|
* image. |
|
* Two image nodes which have the same inode number represent two hardlinks |
|
* of the same file object. So discarding the numbers splits hardlinks. |
|
* |
|
* @param opts |
|
* The option set to be manipulated |
|
* @param new_inos |
|
* 1 = Discard imported inode numbers and finally hand out a unique new |
|
* one to each single file before it gets written into an ISO image. |
|
* 0 = Keep eventual inode numbers from PX entries. |
|
* All other values are reserved. |
|
* @since 0.6.20 |
|
*/ |
|
int iso_read_opts_set_new_inos(IsoReadOpts *opts, int new_inos); |
|
|
|
/** |
|
* Whether to prefer Joliet over RR. libisofs usually prefers RR over |
|
* Joliet, as it give us much more info about files. So, if both extensions |
|
* are present, RR is used. You can set this if you prefer Joliet, but |
|
* note that this is not very recommended. This doesn't mean than RR |
|
* extensions are not read: if no Joliet is present, libisofs will read |
|
* RR tree. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_read_opts_set_preferjoliet(IsoReadOpts *opts, int preferjoliet); |
|
|
|
/** |
|
* How to convert file names if neither Rock Ridge nor Joliet names |
|
* are present and acceptable. |
|
* |
|
* @param opts |
|
* The option set to be manipulated |
|
* @param ecma119_map |
|
* The conversion mode to apply: |
|
* 0 = unmapped: Take name as recorded in ECMA-119 directory record |
|
* (not suitable for writing them to a new ISO filesystem) |
|
* 1 = stripped: Like unmapped, but strip off trailing ";1" or ".;1" |
|
* 2 = uppercase: Like stripped, but map {a-z} to {A-Z} |
|
* 3 = lowercase: Like stripped, but map {A-Z} to {a-z} |
|
* @return |
|
* ISO_SUCCESS if ecma119_map was accepted |
|
* 0 if the value was out of range |
|
* < 0 if other error |
|
* |
|
* @since 1.4.2 |
|
*/ |
|
int iso_read_opts_set_ecma119_map(IsoReadOpts *opts, int ecma119_map); |
|
|
|
/** |
|
* Set default uid for files when RR extensions are not present. |
|
* |
|
* @since 0.6.2 |
|
*/ |
|
int iso_read_opts_set_default_uid(IsoReadOpts *opts, uid_t uid); |
|
|
|
/** |
|