# ioctl_xfs_getbmapx

## NAME



           ioctl_xfs_getbmapx - query extent information for an open file
    


## SYNOPSIS



           **#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



           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
           structure:
    
               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:
    
           _bmv_offset_
                  The file offset of the area of interest in the file.
    
           _bmv_length_
                  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.
    
           _bmv_count_
                  The number of elements in the array, including this header.
                  The minimum value is 2.
    
           _bmv_entries_
                  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.
    
           _bmv_iflags_
                  For the **XFS_IOC_GETBMAPX** function, this is a bitmask
                  containing a combination of the following flags:
    
               **BMV_IF_ATTRFORK**
                      Return information about the extended attribute fork.
    
               **BMV_IF_PREALLOC**
                      Return information about unwritten pre-allocated
                      segments.
    
               **BMV_IF_DELALLOC**
                      Return information about delayed allocation reservation
                      segments.
    
               **BMV_IF_NO_HOLES**
                      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:
    
           _bmv_offset_
                  File offset of segment.
    
           _bmv_block_
                  Physical starting block of segment.  If this is -1, then
                  the segment is a hole.
    
           _bmv_length_
                  Length of segment.
    
           _bmv_oflags_
                  The **XFS_IOC_GETBMAPX** function will fill this field with a
                  combination of the following flags:
    
               **BMV_OF_PREALLOC**
                      The segment is an unwritten pre-allocation.
    
               **BMV_OF_DELALLOC**
                      The segment is a delayed allocation reservation.
    
               **BMV_OF_LAST**
                      This segment is the last in the file.
    
               **BMV_OF_SHARED**
                      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
           returned.
    


## RETURN VALUE



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


## ERRORS



           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.
    
           **EFSBADCRC**
                  Metadata checksum validation failed while performing the
                  query.
    
           **EFSCORRUPTED**
                  Metadata corruption was encountered while performing the
                  query.
    
           **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



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


* * *