Contents

blockmapFile(_:offset:length:flags:operationID:packer:replyHandler:)

Maps a file’s disk space into extents, allowing the kernel to perform I/O with that space.

Declaration

func blockmapFile(_ file: FSItem, offset: off_t, length: Int, flags: FSBlockmapFlags, operationID: FSOperationID, packer: FSExtentPacker, replyHandler reply: @escaping  @Sendable (FSBlockmapResult?, (any Error)?) -> Void)
func blockmapFile(_ file: FSItem, offset: off_t, length: Int, flags: FSBlockmapFlags, operationID: FSOperationID, packer: FSExtentPacker) async throws -> FSBlockmapResult

Parameters

  • file:

    The file for which to map disk space.

  • offset:

    The starting logical offset of the range to be mapped (in bytes).

  • length:

    The length of the range to be mapped (in bytes).

  • flags:

    Flags that affect the behavior of the blockmap operation.

  • operationID:

    A unique identifier of the blockmap call. Any value other than 0 (Objective-C) or Unspecified (Swift) indicates the beginning of an I/O operation. A value of 0 or Unspecified indicates the kernel maps the file without performing I/O. In this case, FSKit doesn’t perform a corresponding call to Completeio(for:offset:length:status:flags:operationid:replyhandler:).

  • packer:

    An extent packer you use to pack the requested range of the file’s allocated disk space. FSKit sends all of the packed extents to the kernel when it invokes reply.

Discussion

::::: Swift ::::::::::

  • reply: A block or closure to indicate success or failure. If mapping succeeds, pass an instance of FSBlockmapResult containing the volume’s updated free space, along with a nil error. If mapping fails, pass the relevant error as the second parameter; FSKit ignores the FSBlockmapResult instance in this case. For an async Swift implementation, there’s no reply handler; simply return the result instance or throw an error.

::::::::::::::::::::

::::: ObjC ::::::::::

  • result: A block or closure to indicate success or failure. If mapping succeeds, pass an instance of FSBlockmapResult containing the volume’s updated free space, along with a nil error. If mapping fails, pass the relevant error as the second parameter; FSKit ignores the FSBlockmapResult instance in this case. For an async Swift implementation, there’s no reply handler; simply return the result instance or throw an error.

::::::::::::::::::::

Discussion

FSKit calls this method when the kernel needs to get a mapping of logical-to-physical offsets of the file’s data. This call may occur as part of an I/O operation on the file, or just to get the mapping as part of an fcntl(F_LOG2PHYS) system call. In the case of an I/O operation on the file, operationID has a nonzero value; a future call to completeIO(for:offset:length:status:flags:operationID:replyHandler:) uses the same operationID to indicate which operation it completes. In the case of an fcntl(F_LOG2PHYS) system call, the operationID parameter is 0 (Objective-C) or unspecified (Swift). In both cases the kernel retains the mapping, and it may perform I/O to this range (or a part of it) at any time.

If satisfying a blockmap request requires more extents than packer can handle, FSKit makes additional calls to this method with the same operation ID to collect the remainder.

See Also

Performing mapped I/O