<trclass="memdesc:a8fc1d6adf1ec5cc7d7bb9c067aff9f6e"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Creates a new AaruFormat image file. <br/></td></tr>
<p>Allocates and initializes a new aaruformat context and image file with the specified parameters. This function sets up all necessary data structures including headers, DDT (deduplication table), caches, and index entries for writing a new AaruFormat image. It also handles file creation, memory allocation, and proper initialization of the writing context. The function supports both block-based media (disks, optical media) and sequential tape media with different initialization strategies optimized for each media type.</p>
<p><b>Media Type Handling:</b> The function creates different internal structures based on the <spanclass="tt">is_tape</span> parameter:</p>
<p><b>Block Media (is_tape = false):</b></p><ul>
<li>Initializes full DDT (Deduplication Table) version 2 for sector-level deduplication</li>
<li>Allocates primary DDT table (userDataDdtMini or userDataDdtBig) as a preallocated array</li>
<li>Configures multi-level DDT support for large images (> 138,412,552 sectors)</li>
<li>Enables optional deduplication hash map for detecting duplicate sectors</li>
<li>Reserves space for DDT at the beginning of the file (after header, block-aligned)</li>
<li>Data blocks start after DDT table to maintain sequential layout</li>
<li>DDT size is fixed and known upfront based on sector count</li>
</ul>
<p><b>Tape Media (is_tape = true):</b></p><ul>
<li>Initializes DDT for sector-level deduplication using a different strategy</li>
<li>Uses a growing hash table (tapeDdt) instead of a preallocated array</li>
<li>Sets ctx->is_tape flag and initializes ctx->tapeDdt to NULL (populated on first write)</li>
<li>Data blocks start immediately after the header (block-aligned)</li>
<li>Hash table grows dynamically as blocks are written</li>
<li>Optimized for sequential write patterns typical of tape media</li>
<li>Tape file/partition metadata is managed separately via additional hash tables</li>
<li>More memory-efficient for tapes with unknown final size</li>
<li>Primary DDT placed immediately after header (block-aligned)</li>
<li>Data blocks positioned after DDT table (block-aligned)</li>
<li>Alignment controlled by blockAlignmentShift from options</li>
</ul>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">filepath</td><td>Path to the image file to create. The file will be created if it doesn't exist, or overwritten if it does. Must be a valid writable path.</td></tr>
<tr><tdclass="paramname">media_type</td><td>Media type identifier (e.g., CompactDisc, DVD, HardDisk, Tape formats). This affects how the image is structured and which features are enabled.</td></tr>
<tr><tdclass="paramname">sector_size</td><td>Size of each sector/block in bytes. Common values:<ul>
<li>512 bytes: Hard disks, floppy disks</li>
<li>2048 bytes: CD-ROM, DVD</li>
<li>Variable: Tape media (block size varies by format)</li>
</ul>
</td></tr>
<tr><tdclass="paramname">user_sectors</td><td>Number of user data sectors/blocks in the image. This is the main data area excluding negative (lead-in) and overflow (lead-out) regions. For tape media, this may be an estimate as the final size is often unknown.</td></tr>
<tr><tdclass="paramname">negative_sectors</td><td>Number of negative sectors (typically lead-in area for optical media). Set to 0 for media types without lead-in areas. Not used for tape media.</td></tr>
<tr><tdclass="paramname">overflow_sectors</td><td>Number of overflow sectors (typically lead-out area for optical media). Set to 0 for media types without lead-out areas. Not used for tape media.</td></tr>
<tr><tdclass="paramname">options</td><td>String with creation options in key=value format, semicolon-separated. Supported options:<ul>
<li>"deduplicate=true|false": Enable/disable sector deduplication (all media types)</li>
<li>"md5=true|false": Calculate MD5 checksum during write</li>
<li>"sha1=true|false": Calculate SHA-1 checksum during write</li>
<li>"sha256=true|false": Calculate SHA-256 checksum during write</li>
<li>"spamsum=true|false": Calculate SpamSum fuzzy hash during write</li>
<li>"blake3=true|false": Calculate BLAKE3 checksum during write</li>
<li>"block_alignment=N": Block alignment shift value (default varies)</li>
<li>"data_shift=N": Data shift value for DDT granularity</li>
<li>"table_shift=N": Table shift for multi-level DDT (-1 for auto, block media only)</li>
<li>"dictionary=N": LZMA dictionary size in bytes Example: "compress=true;deduplicate=true;md5=true;sha1=true"</li>
</ul>
</td></tr>
<tr><tdclass="paramname">application_name</td><td>Pointer to the application name string (UTF-8 encoded). This identifies the software that created the image. The string will be copied directly to the image header.</td></tr>
<tr><tdclass="paramname">application_name_length</td><td>Length of the application name string in bytes. Must be ≤ AARU_HEADER_APP_NAME_LEN (64 bytes).</td></tr>
<tr><tdclass="paramname">application_major_version</td><td>Major version of the creating application (0-255).</td></tr>
<tr><tdclass="paramname">application_minor_version</td><td>Minor version of the creating application (0-255).</td></tr>
<tr><tdclass="paramname">is_tape</td><td>Boolean flag indicating tape media type:<ul>
<li>true: Initialize for tape media (sequential, dynamic hash table DDT, file/partition metadata)</li>
<li>false: Initialize for block media (random access, preallocated array DDT)</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dlclass="section return"><dt>Returns</dt><dd>Returns one of the following: </dd></dl>
<dlclass="retval"><dt>Return values</dt><dd>
<tableclass="retval">
<tr><tdclass="paramname">aaruformatContext*</td><td>Successfully created and initialized context. The returned pointer contains:<ul>
<li>Properly initialized AaruFormat headers and metadata</li>
<li>For block media: Allocated and configured DDT structures with preallocated arrays</li>
<li>For tape media: Tape flags set, DDT initialized as NULL (grows on demand)</li>
<li>Initialized block and header caches for performance</li>
<li>Open file stream ready for writing operations</li>
<li>Index entries array ready for block tracking</li>
<li>ECC context initialized for Compact Disc support</li>
<li>Checksum contexts initialized based on options</li>
</ul>
</td></tr>
<tr><tdclass="paramname">NULL</td><td>Creation failed. The specific error can be determined by checking errno, which will be set to:<ul>
<li>AARUF_ERROR_NOT_ENOUGH_MEMORY (-9) when memory allocation fails for:<ul>
<li>Context allocation</li>
<li>Readable sector tags array allocation</li>
<li>Application version string allocation</li>
<li>Image version string allocation</li>
<li>DDT table allocation (userDataDdtMini or userDataDdtBig, block media only)</li>
<li>Index entries array allocation</li>
</ul>
</li>
<li>AARUF_ERROR_CANNOT_CREATE_FILE (-19) when file operations fail:<ul>
<li>Unable to open the specified filepath for writing</li>
<li>File seek operations fail during initialization</li>
<li>The function performs extensive memory allocation for various context structures</li>
<li>On failure, all previously allocated memory is properly cleaned up</li>
<li>The returned context must be freed using <aclass="el"href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49"title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a> when finished</li>
</ul>
</dd>
<dd>
File Operations:<ul>
<li>Creates a new file at the specified path (overwrites existing files)</li>
<li>Opens the file in binary read/write mode ("wb+")</li>
<li>Positions the file pointer at the calculated data start position</li>
<li>File alignment is handled based on parsed options</li>
</ul>
</dd>
<dd>
DDT Initialization (Block Media Only):<ul>
<li>Uses DDT version 2 format with configurable compression and alignment</li>
<li>Calculates optimal table sizes based on sector counts and shift parameters</li>
<li>All DDT entries are initialized to zero (indicating unallocated sectors)</li>
<li>Multi-level DDT is used for images with ≥ 138,412,552 total sectors</li>
<li>Single-level DDT is used for smaller images for efficiency</li>
<li>DDT is a fixed-size preallocated array written to file at known offset</li>
</ul>
</dd>
<dd>
Tape Media Initialization:<ul>
<li>Tape images use a dynamic hash table DDT for sector-level deduplication</li>
<li>File and partition metadata is managed via separate hash tables</li>
<li>ctx->is_tape is set to 1 to indicate tape mode throughout the library</li>
<li>ctx->tapeDdt is initialized to NULL and grows dynamically as blocks are written</li>
<li>Data blocks can start immediately after header for optimal sequential access</li>
<li>The hash table DDT allows for efficient deduplication without knowing final size</li>
<li>More memory-efficient for tapes with unpredictable or very large sizes</li>
<li>Deduplication hash map may still be used alongside tapeDdt if enabled in options</li>
</ul>
</dd>
<dd>
Options Parsing:<ul>
<li>The options string is parsed to extract block_alignment, data_shift, and table_shift</li>
<li>These parameters affect memory usage, performance, and file organization</li>
<li>Invalid options may result in suboptimal performance but won't cause failure</li>
<li>Compression and checksums can be enabled independently via options</li>
</ul>
</dd>
<dd>
Checksum Initialization:<ul>
<li>MD5, SHA-1, SHA-256, SpamSum, and BLAKE3 can be calculated during write</li>
<li>Checksum contexts are initialized only if requested in options</li>
<li><aclass="el"href="structChecksums.html"title="Collected whole‑image checksums / hashes present in a checksum block.">Checksums</a> are computed incrementally as sectors/blocks are written</li>
<li>Final checksums are stored in checksum block during image finalization</li>
</ul>
</dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>The created context is in writing mode and expects proper finalization before closing to ensure index and metadata are written correctly.</dd>
<dd>
Application name length validation is strict - exceeding the limit will cause creation failure with AARUF_ERROR_INVALID_APP_NAME_LENGTH.</dd>
<dd>
For tape media, the DDT structure is fundamentally different (hash table vs array). The is_tape flag must accurately reflect the media type being created.</dd>
<dd>
The negative_sectors and overflow_sectors parameters are used only for block media. For tape media, these parameters are ignored.</dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49"title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a> for proper context cleanup and image finalization </dd>
<dd>
<aclass="el"href="decls_8h.html#a4b8cd2bb5fd9e2c670a0a13695c6f9e3"title="Writes a sector to the AaruFormat image.">aaruf_write_sector()</a> for writing sectors to block media images </dd>
<dd>
<aclass="el"href="decls_8h.html#a01c915ab49a4b47fd6768a2055208c48"title="Sets or updates the block range for a specific tape file in an Aaru tape image.">aaruf_set_tape_file()</a> for defining tape file metadata </dd>
<dd>
<aclass="el"href="decls_8h.html#a9daeeb54c74dd2707d95ab47e8ab0a00"title="Sets or updates the block range for a specific tape partition in an Aaru tape image.">aaruf_set_tape_partition()</a> for defining tape partition metadata </dd></dl>
<p>< Size in bytes (UTF-16LE) of application name field (32 UTF-16 code units).</p>
<pclass="definition">Definition at line <aclass="el"href="create_8c_source.html#l00279">279</a> of file <aclass="el"href="create_8c_source.html">create.c</a>.</p>
<pclass="definition">Definition at line <aclass="el"href="create_8c_source.html#l00030">30</a> of file <aclass="el"href="create_8c_source.html">create.c</a>.</p>
<liclass="footer">Generated by <ahref="https://www.doxygen.org/index.html"><imgclass="footer"src="doxygen.svg"width="104"height="31"alt="doxygen"/></a> 1.14.0 </li>
