You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
9469 lines
330 KiB
C
9469 lines
330 KiB
C
|
|
#ifndef LIBISO_LIBISOFS_H_
|
|
#define LIBISO_LIBISOFS_H_
|
|
|
|
/*
|
|
* Copyright (c) 2007-2008 Vreixo Formoso, Mario Danic
|
|
* Copyright (c) 2009-2021 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 5
|
|
#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 libraries 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
|
|
* explicitly 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 adding 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.
|
|
* Predefined (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 function
|
|
* is not needed at all, each time that the underlying system resource
|
|
* needs to be accessed, it is opened property.
|
|
* 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 previously opened 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
|
|
* must not 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)
|
|
* 2 means success, but it is possible that attributes
|
|
* exist in non-user namespaces which could not be
|
|
* explored due to lack of permission.
|
|
* @since 1.5.0
|
|
* <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);
|
|
|
|
/**
|
|
* Inquire and maybe define the time which is considered to be "now" and
|
|
* used for timestamps of freshly created ISO nodes and as default of
|
|
* image timestamps.
|
|
* If ever, this should normally be enabled and defined before iso_image_new().
|
|
* If it is disabled, time(NULL) is considered to be "now".
|
|
*
|
|
* @param now
|
|
* Returns the "now" value and maybe submits it as definition.
|
|
* @param flag
|
|
* Bitfield for control purposes
|
|
* bit0= *now contains the time to be set as nowtime override.
|
|
Enable the override if not bit1 is set, too.
|
|
* bit1= Disable the nowtime override
|
|
* @return 1= *now is not overridden , 2= *now is overridden
|
|
*
|
|
* @since 1.5.2
|
|
*/
|
|
int iso_nowtime(time_t *now, 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
|
|
* bit3= if not bit1: import all xattr namespaces, not only "user."
|
|
* @since 1.5.0
|
|
* all other bits are reserved
|
|
*
|
|
* @since 0.6.14
|
|
*/
|
|
void iso_image_set_ignore_aclea(IsoImage *image, int what);
|
|
|
|
|
|
/**
|
|
* Obtain the current setting of iso_image_set_ignore_aclea().
|
|
*
|
|
* @param image
|
|
* The image to be inquired
|
|
* @return
|
|
* The currently set value.
|
|
*
|
|
* @since 1.5.0
|
|
*/
|
|
int iso_image_get_ignore_aclea(IsoImage *image);
|
|
|
|
|
|
/**
|
|
* 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+ filesystem.
|
|
* 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 overridden
|
|
* 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 information 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 constraints, 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 overwritable 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 overwritable 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 overwritable 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 overwritable 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 overwritable 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 enough.
|
|
* 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
|
|
* @since 1.4.4
|
|
* Enforce MBR "bootable/active" flag. In worst case by dummy
|
|
* partition of type 0x00 which occupies block 0.
|
|
* bit16= "Legacy BIOS bootable" in GPT
|
|
* @since 1.5.6
|
|
* If this bit is set and a GPT partition for the ISO 9660
|
|
* filesystem gets written, then set the GPT partition flags bit 2
|
|
* "Legacy BIOS bootable".
|
|
* bit17= ISO not read-only
|
|
* @since 1.5.6
|
|
* Do not set GPT partition flag bit 60 "read-only" for the
|
|
* ISO 9660 filesystem partition, if such a partition gets
|
|
* written.
|
|
* @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);
|
|
|
|
/**
|
|
* Explicitly 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 2
|
|
#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 partition 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 from the text
|
|
* form as prescribed by UEFI specs:
|
|
* 4 byte, 2 byte, 2 byte as little-endian.
|
|
* 2 byte, 6 byte 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);
|
|
|
|
/**
|
|
* Set the GPT Type GUID for a partition defined by
|
|
* iso_write_opts_set_partition_img().
|
|
*
|
|
* @param opts
|
|
* The option set to be manipulated.
|
|
* @param partition_number
|
|
* Depicts the partition table entry which shall get the Type GUID.
|
|
* @param guid
|
|
* 16 bytes of user supplied GUID. Readily byte-swapped from the text
|
|
* form as prescribed by UEFI specs:
|
|
* 4 byte, 2 byte, 2 byte as little-endian.
|
|
* 2 byte, 6 byte as big-endian.
|
|
* @param valid
|
|
* Set to 1 to make this Type GUID valid.
|
|
* Set to 0 in order to invalidate a previously made setting. In this
|
|
* case MBR type 0xEF will become the EFI Type GUID. All others will
|
|
* become the Basic Data Partition Type GUID.
|
|
* @return
|
|
* ISO_SUCCESS or error
|
|
*
|
|
* @since 1.5.2
|
|
*/
|
|
int iso_write_opts_set_part_type_guid(IsoWriteOpts *opts, int partition_number,
|
|
uint8_t guid[16], int valid);
|
|
|
|
/**
|
|
* 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);
|
|
|
|
/**
|
|
* Set the partition type of the MBR partition which represents the ISO
|
|
* filesystem or at least protects it.
|
|
* This is without effect if no such partition emerges by other settings or
|
|
* if the partition type is prescribed mandatorily like 0xee for GPT protective
|
|
* MBR or 0x96 for CHRP.
|
|
* @param opts
|
|
* The option set to be manipulated.
|
|
* @param part_type
|
|
* 0x00 to 0xff as desired partition type.
|
|
* Any other value (e.g. -1) enables the default types of the various
|
|
* occasions.
|
|
* @return
|
|
* ISO_SUCCESS or error
|
|
* @since 1.4.8
|
|
*/
|
|
int iso_write_opts_set_iso_mbr_part_type(IsoWriteOpts *opts, int part_type);
|
|
|
|
/**
|
|
* Set the GPT Type GUID for the partition which represents the ISO 9660
|
|
* filesystem, if such a partition emerges in GPT.
|
|
* @param opts
|
|
* The option set to be manipulated.
|
|
* @param guid
|
|
* 16 bytes of user supplied GUID. Readily byte-swapped from the text
|
|
* form as prescribed by UEFI specs:
|
|
* 4 byte, 2 byte, 2 byte as little-endian.
|
|
* 2 byte, 6 byte as big-endian.
|
|
* @param valid
|
|
* Set to 1 to make this Type GUID valid.
|
|
* Set to 0 in order to invalidate a previously made setting. In this
|
|
* case the setting of iso_write_opts_set_iso_mbr_part_type() or its
|
|
* default will get into effect.
|
|
* @return
|
|
* ISO_SUCCESS or error
|
|
*
|
|
* @since 1.5.2
|
|
*/
|
|
int iso_write_opts_set_iso_type_guid(IsoWriteOpts *opts, uint8_t guid[16],
|
|
int valid);
|
|
|
|
/**
|
|
* 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 information 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 it 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);
|
|
|
|
/**
|
|
* How to convert Joliet file names.
|
|
*
|
|
* @param opts
|
|
* The option set to be manipulated
|
|
* @param ecma119_map
|
|
* The conversion mode to apply:
|
|
* 0 = unmapped: Take name as recorded in Joliet directory record
|
|
* (not suitable for writing it to a new ISO filesystem)
|
|
* 1 = stripped: Strip off trailing ";1" or ".;1"
|
|
* @return
|
|
* ISO_SUCCESS if joliet_map was accepted
|
|
* 0 if the value was out of range
|
|
* < 0 if other error
|
|
*
|
|
* @since 1.5.4
|
|
*/
|
|
int iso_read_opts_set_joliet_map(IsoReadOpts *opts, int joliet_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);
|
|
|
|
/**
|
|
* Set default gid for files when RR extensions are not present.
|
|
*
|
|
* @since 0.6.2
|
|
*/
|
|
int iso_read_opts_set_default_gid(IsoReadOpts *opts, gid_t gid);
|
|
|
|
/**
|
|
* Set default permissions for files when RR extensions are not present.
|
|
*
|
|
* @param opts
|
|
* The option set to be manipulated
|
|
* @param file_perm
|
|
* Permissions for files.
|
|
* @param dir_perm
|
|
* Permissions for directories.
|
|
*
|
|
* @since 0.6.2
|
|
*/
|
|
int iso_read_opts_set_default_permissions(IsoReadOpts *opts, mode_t file_perm,
|
|
mode_t dir_perm);
|
|
|
|
/**
|
|
* Set the input charset of the file names on the image. NULL to use locale
|
|
* charset. You have to specify a charset if the image filenames are encoded
|
|
* in a charset different that the local one. This could happen, for example,
|
|
* if the image was created on a system with different charset.
|
|
*
|
|
* @param opts
|
|
* The option set to be manipulated
|
|
* @param charset
|
|
* The charset to use as input charset. You can obtain the list of
|
|
* charsets supported on your system executing "iconv -l" in a shell.
|
|
*
|
|
* @since 0.6.2
|
|
*/
|
|
int iso_read_opts_set_input_charset(IsoReadOpts *opts, const char *charset);
|
|
|
|
/**
|
|
* Enable or disable methods to automatically choose an input charset.
|
|
* This eventually overrides the name set via iso_read_opts_set_input_charset()
|
|
*
|
|
* @param opts
|
|
* The option set to be manipulated
|
|
* @param mode
|
|
* Bitfield for control purposes:
|
|
* bit0= Allow to use the input character set name which is eventually
|
|
* stored in attribute "isofs.cs" of the root directory.
|
|
* Applications may attach this xattr by iso_node_set_attrs() to
|
|
* the root node, call iso_write_opts_set_output_charset() with the
|
|
* same name and enable iso_write_opts_set_aaip() when writing
|
|
* an image.
|
|
* Submit any other bits with value 0.
|
|
*
|
|
* @since 0.6.18
|
|
*
|
|
*/
|
|
int iso_read_opts_auto_input_charset(IsoReadOpts *opts, int mode);
|
|
|
|
/**
|
|
* Enable or disable loading of the first 32768 bytes of the session.
|
|
*
|
|
* @param opts
|
|
* The option set to be manipulated
|
|
* @param mode
|
|
* Bitfield for control purposes:
|
|
* bit0= Load System Area data and attach them to the image so that they
|
|
* get written by the next session, if not overridden by
|
|
* iso_write_opts_set_system_area().
|
|
* Submit any other bits with value 0.
|
|
*
|
|
* @since 0.6.30
|
|
*
|
|
*/
|
|
int iso_read_opts_load_system_area(IsoReadOpts *opts, int mode);
|
|
|
|
/**
|
|
* Control whether to keep a reference to the IsoDataSource object which
|
|
* allows access to the blocks of the imported ISO 9660 filesystem.
|
|
* This is needed if the interval reader shall read from "imported_iso".
|
|
*
|
|
* @param opts
|
|
* The option set to be manipulated
|
|
* @param mode
|
|
* Bitfield for control purposes:
|
|
* bit0= Keep a reference to the IsoDataSource until the IsoImage object
|
|
* gets disposed by its final iso_image_unref().
|
|
* Submit any other bits with value 0.
|
|
*
|
|
* @since 1.4.0
|
|
*
|
|
*/
|
|
int iso_read_opts_keep_import_src(IsoReadOpts *opts, int mode);
|
|
|
|
/**
|
|
* Import a previous session or image, for growing or modify.
|
|
*
|
|
* @param image
|
|
* The image context to which old image will be imported. Note that all
|
|
* files added to image, and image attributes, will be replaced with the
|
|
* contents of the old image.
|
|
* TODO #00025 support for merging old image files
|
|
* @param src
|
|
* Data Source from which old image will be read. A extra reference is
|
|
* added, so you still need to iso_data_source_unref() yours.
|
|
* @param opts
|
|
* Options for image import. All needed data will be copied, so you
|
|
* can free the given struct once this function returns.
|
|
* @param features
|
|
* If not NULL, a new IsoReadImageFeatures will be allocated and filled
|
|
* with the features of the old image. It should be freed with
|
|
* iso_read_image_features_destroy() when no more needed. You can pass
|
|
* NULL if you're not interested on them.
|
|
* @return
|
|
* 1 on success, < 0 on error
|
|
*
|
|
* @since 0.6.2
|
|
*/
|
|
int iso_image_import(IsoImage *image, IsoDataSource *src, IsoReadOpts *opts,
|
|
IsoReadImageFeatures **features);
|
|
|
|
/**
|
|
* Destroy an IsoReadImageFeatures object obtained with iso_image_import.
|
|
*
|
|
* @since 0.6.2
|
|
*/
|
|
void iso_read_image_features_destroy(IsoReadImageFeatures *f);
|
|
|
|
/**
|
|
* Get the size (in 2048 byte block) of the image, as reported in the PVM.
|
|
*
|
|
* @since 0.6.2
|
|
*/
|
|
uint32_t iso_read_image_features_get_size(IsoReadImageFeatures *f);
|
|
|
|
/**
|
|
* Whether RockRidge extensions are present in the image imported.
|
|
*
|
|
* @since 0.6.2
|
|
*/
|
|
int iso_read_image_features_has_rockridge(IsoReadImageFeatures *f);
|
|
|
|
/**
|
|
* Whether Joliet extensions are present in the image imported.
|
|
*
|
|
* @since 0.6.2
|
|
*/
|
|
int iso_read_image_features_has_joliet(IsoReadImageFeatures *f);
|
|
|
|
/**
|
|
* Whether the image is recorded according to ISO 9660:1999, i.e. it has
|
|
* a version 2 Enhanced Volume Descriptor.
|
|
*
|
|
* @since 0.6.2
|
|
*/
|
|
int iso_read_image_features_has_iso1999(IsoReadImageFeatures *f);
|
|
|
|
/**
|
|
* Whether El-Torito boot record is present present in the image imported.
|
|
*
|
|
* @since 0.6.2
|
|
*/
|
|
int iso_read_image_features_has_eltorito(IsoReadImageFeatures *f);
|
|
|
|
/**
|
|
* Tells what directory tree was loaded:
|
|
* 0= ISO 9660 , 1 = Joliet , 2 = ISO 9660:1999
|
|
*
|
|
* @since 1.5.4
|
|
*/
|
|
int iso_read_image_features_tree_loaded(IsoReadImageFeatures *f);
|
|
|
|
/**
|
|
* Tells whether Rock Ridge information was used while loading the tree:
|
|
* 1= yes, 0= no
|
|
*
|
|
* @since 1.5.4
|
|
*/
|
|
int iso_read_image_features_rr_loaded(IsoReadImageFeatures *f);
|
|
|
|
/**
|
|
* Increments the reference counting of the given image.
|
|
*
|
|
* @since 0.6.2
|
|
*/
|
|
void iso_image_ref(IsoImage *image);
|
|
|
|
/**
|
|
* Decrements the reference counting of the given image.
|
|
* If it reaches 0, the image is free, together with its tree nodes (whether
|
|
* their refcount reach 0 too, of course).
|
|
*
|
|
* @since 0.6.2
|
|
*/
|
|
void iso_image_unref(IsoImage *image);
|
|
|
|
/**
|
|
* Attach user defined data to the image. Use this if your application needs
|
|
* to store addition info together with the IsoImage. If the image already
|
|
* has data attached, the old data will be freed.
|
|
*
|
|
* @param image
|
|
* The image to which data shall be attached.
|
|
* @param data
|
|
* Pointer to application defined data that will be attached to the
|
|
* image. You can pass NULL to remove any already attached data.
|
|
* @param give_up
|
|
* Function that will be called when the image does not need the data
|
|
* any more. It receives the data pointer as an argumente, and eventually
|
|
* causes data to be freed. It can be NULL if you don't need it.
|
|
* @return
|
|
* 1 on success, < 0 on error
|
|
*
|
|
* @since 0.6.2
|
|
*/
|
|
int iso_image_attach_data(IsoImage *image, void *data, void (*give_up)(void*));
|
|
|
|
/**
|
|
* The the data previously attached with iso_image_attach_data()
|
|
*
|
|
* @since 0.6.2
|
|
*/
|
|
void *iso_image_get_attached_data(IsoImage *image);
|
|
|
|
/**
|
|
* Set the name truncation mode and the maximum name length for nodes from
|
|
* image importing, creation of new IsoNode objects, and name changing image
|
|
* manipulations.
|
|
*
|
|
* Truncated names are supposed to be nearly unique because they end by the MD5
|
|
* of the first 4095 characters of the untruncated name. One should treat them
|
|
* as if they were the untruncated original names.
|
|
*
|
|
* For proper processing of truncated names it is necessary to use
|
|
* iso_image_set_node_name() instead of iso_node_set_name()
|
|
* iso_image_add_new_dir() iso_tree_add_new_dir()
|
|
* iso_image_add_new_file() iso_tree_add_new_file()
|
|
* iso_image_add_new_special() iso_tree_add_new_special()
|
|
* iso_image_add_new_symlink() iso_tree_add_new_symlink()
|
|
* iso_image_tree_clone() iso_tree_clone()
|
|
* iso_image_dir_get_node() iso_dir_get_node()
|
|
* iso_image_path_to_node() iso_tree_path_to_node()
|
|
*
|
|
* Beware of ambiguities if both, the full name and the truncated name,
|
|
* exist in the same directory. Best is to only set truncation parameters
|
|
* once with an ISO filesystem and to never change them later.
|
|
*
|
|
* If writing of AAIP is enabled, then the mode and length are recorded in
|
|
* xattr "isofs.nt" of the root node.
|
|
* If reading of AAIP is enabled and "isofs.nt" is found, then it gets into
|
|
* effect if both, the truncate mode value from "isofs.nt" and the current
|
|
* truncate mode of the IsoImage are 1, and the length is between 64 and 255.
|
|
*
|
|
* @param img
|
|
* The image which shall be manipulated.
|
|
* @param mode
|
|
* 0= Do not truncate but throw error ISO_RR_NAME_TOO_LONG if a file name
|
|
* is longer than parameter length.
|
|
* 1= Truncate to length and overwrite the last 33 bytes of that length
|
|
* by a colon ':' and the hex representation of the MD5 of the first
|
|
* 4095 bytes of the whole oversized name.
|
|
* Potential incomplete UTF-8 characters will get their leading bytes
|
|
* replaced by '_'.
|
|
* Mode 1 is the default.
|
|
* @param length
|
|
* Maximum byte count of a file name. Permissible values are 64 to 255.
|
|
* Default is 255.
|
|
* @return
|
|
* ISO_SUCCESS or ISO_WRONG_ARG_VALUE
|
|
*
|
|
* @since 1.4.2
|
|
*/
|
|
int iso_image_set_truncate_mode(IsoImage *img, int mode, int length);
|
|
|
|
/**
|
|
* Inquire the current setting of iso_image_set_truncate_mode().
|
|
*
|
|
* @param img
|
|
* The image which shall be inquired.
|
|
* @param mode
|
|
* Returns the mode value.
|
|
* @param length
|
|
* Returns the length value.
|
|
* @return
|
|
* ISO_SUCCESS or <0 = error
|
|
*
|
|
* @since 1.4.2
|
|
*/
|
|
int iso_image_get_truncate_mode(IsoImage *img, int *mode, int *length);
|
|
|
|
/**
|
|
* Immediately apply the given truncate mode and length to the given string.
|
|
*
|
|
* @param mode
|
|
* See iso_image_set_truncate_mode()
|
|
* @param length
|
|