ioctl_xfs_getbmapx(2) — Linux manual page


IOCTL-XFS-GETBMAPX(2)      System Calls Manual     IOCTL-XFS-GETBMAPX(2)

NAME         top

       ioctl_xfs_getbmapx - query extent information for an open file

SYNOPSIS         top

       #include <xfs/xfs_fs.h>

       int ioctl(int fd, XFS_IOC_GETBMAP, struct getbmap *arg);
       int ioctl(int fd, XFS_IOC_GETBMAPA, struct getbmap *arg);
       int ioctl(int fd, XFS_IOC_GETBMAPX, struct getbmapx *arg);

DESCRIPTION         top

       Get the block map for a segment of a file in an XFS file system.
       The mapping information is conveyed via an array of structures of
       the following form:

           struct getbmap {
                __s64   bmv_offset;
                __s64   bmv_block;
                __s64   bmv_length;
                __s32   bmv_count;
                __s32   bmv_entries;

       The XFS_IOC_GETBMAPX ioctl uses a larger version of that

           struct getbmapx {
                __s64   bmv_offset;
                __s64   bmv_block;
                __s64   bmv_length;
                __s32   bmv_count;
                __s32   bmv_entries;
                __s32   bmv_iflags;
                __s32   bmv_oflags;
                __s32   bmv_unused1;
                __s32   bmv_unused2;

       All sizes and offsets in the structure are in units of 512 bytes.

       The first structure in the array is a header and the remaining
       structures in the array contain block map information on return.
       The header controls iterative calls to the command and should be
       filled out as follows:

              The file offset of the area of interest in the file.

              The length of the area of interest in the file.  If this
              value is set to -1, the length of the interesting area is
              the rest of the file.

              The number of elements in the array, including this
              header.  The minimum value is 2.

              The number of entries actually filled in by the call.
              This does not need to be filled out before the call.  This
              value may be zero if no extents were found in the
              requested range, or if iterated calls have reached the end
              of the requested range.

              For the XFS_IOC_GETBMAPX function, this is a bitmask
              containing a combination of the following flags:

                  Return information about the extended attribute fork.

                  Return information about unwritten pre-allocated

                  Return information about delayed allocation
                  reservation segments.

                  Do not return information about holes.

       The other bmv_* fields in the header are ignored.

       On successful return from a call, the offset and length values in
       the header are updated so that the command can be reused to
       obtain more information.  The remaining elements of the array
       will be filled out by the call as follows:

              File offset of segment.

              Physical starting block of segment.  If this is -1, then
              the segment is a hole.

              Length of segment.

              The XFS_IOC_GETBMAPX function will fill this field with a
              combination of the following flags:

                  The segment is an unwritten pre-allocation.

                  The segment is a delayed allocation reservation.

                  This segment is the last in the file.

                  This segment shares blocks with other files.

       The other bmv_* fields are unused in the array of output records.

       The XFS_IOC_GETBMAPA command is identical to XFS_IOC_GETBMAP
       except that information about the attribute fork of the file is

RETURN VALUE         top

       On error, -1 is returned, and errno is set to indicate the error.

ERRORS         top

       Error codes can be one of, but are not limited to, the following:

       EFAULT The kernel was not able to copy into the userspace buffer.

              Metadata checksum validation failed while performing the

              Metadata corruption was encountered while performing the

       EINVAL One of the arguments was not valid.

       EIO    An I/O error was encountered while performing the query.

       ENOMEM There was insufficient memory to perform the query.

CONFORMING TO         top

       This API is specific to XFS filesystem on the Linux kernel.

SEE ALSO         top


COLOPHON         top

       This page is part of the xfsprogs (utilities for XFS filesystems)
       project.  Information about the project can be found at 
       ⟨⟩.  If you have a bug report for this manual page,
       send it to  This page was obtained
       from the project's upstream Git repository
       ⟨⟩ on
       2023-12-22.  (At that time, the date of the most recent commit
       that was found in the repository was 2023-10-12.)  If you
       discover any rendering problems in this HTML version of the page,
       or you believe there is a better or more up-to-date source for
       the page, or you have corrections or improvements to the
       information in this COLOPHON (which is not part of the original
       manual page), send a mail to

XFS                            2019-06-17          IOCTL-XFS-GETBMAPX(2)

Pages that refer to this page: xfsctl(3)