title: io_uring_setup(2)

text:
# io_uring_setup(2)

## NAME
io_uring_setup - setup a context for performing asynchronous I/O

## SYNOPSIS

```
#include <liburing.h>
```

```
int io_uring_setup(u32 entries, struct io_uring_params *params);
```

## DESCRIPTION
The io_uring_setup(2) system call sets up a submission queue (SQ) and completion queue (CQ) with at least entries entries, and returns a file descriptor which can be used to perform subsequent operations on the io_uring instance. The submission and completion queues are shared between userspace and the kernel, which eliminates the need to copy data when initiating and completing I/O.

params is used by the application to pass options to the kernel, and by the kernel to convey information about the ring buffers.

```
struct io_uring_params {

    __u32 sq_entries;

    __u32 cq_entries;

    __u32 flags;

    __u32 sq_thread_cpu;

    __u32 sq_thread_idle;

    __u32 features;

    __u32 wq_fd;

    __u32 resv[3];

    struct io_sqring_offsets sq_off;

    struct io_cqring_offsets cq_off;
};
```

The flags, sq_thread_cpu, and sq_thread_idle fields are used to configure the io_uring instance. flags is a bit mask of 0 or more of the following values ORed together:

IORING_SETUP_IOPOLL

Perform busy-waiting for an I/O completion, as opposed to getting notifications via an asynchronous IRQ (Interrupt Request). The file system (if any) and block device must support polling in order for this to work. Busy-waiting provides lower latency, but may consume more CPU resources than interrupt driven I/O. Currently, this feature is usable only on a file descriptor opened using the O_DIRECT flag. When a read or write is submitted to a polled context, the application must poll for completions on the CQ ring by calling io_uring_enter(2). It is illegal to mix and match polled and non-polled I/O on an io_uring instance. This is only applicable for storage devices for now, and the storage device must be configured for polling. How to do that depends on the device type in question. For NVMe devices, the nvme driver must be loaded with the poll_queues parameter set to the desired number of polling queues. The polling queues will be shared appropriately between the CPUs in the system, if the number is less than the number of online CPU threads.

IORING_SETUP_HYBRID_IOPOLL

This flag must be used with IORING_SETUP_IOPOLL flag. Hybrid io polling is a feature based on iopoll, it differs from strict polling in that it will delay a bit before doing completion side polling, to avoid wasting too much CPU resources. Like IOPOLL , it requires that devices support polling.

IORING_SETUP_SQPOLL

When this flag is specified, a kernel thread is created to perform submission queue polling. An io_uring instance configured in this way enables an application to issue I/O without ever context switching into the kernel. By using the submission queue to fill in new submission queue entries and watching for completions on the completion queue, the application can submit and reap I/Os without doing a single system call. If the kernel thread is idle for more than sq_thread_idle milliseconds, it will set the IORING_SQ_NEED_WAKEUP bit in the flags field of the struct io_sq_ring. When this happens, the application must call io_uring_enter(2) to wake the kernel thread. If I/O is kept busy, the kernel thread will never sleep. An application making use of this feature will need to guard the io_uring_enter(2) call with the following code sequence:

```
/*

 * Ensure that the wakeup flag is read after the tail pointer

 * has been written. It's important to use memory load acquire

 * semantics for the flags read, as otherwise the application

 * and the kernel might not agree on the consistency of the

 * wakeup flag.

 */
unsigned flags = atomic_load_relaxed(sq_ring->flags);
if (flags & IORING_SQ_NEED_WAKEUP)

    io_uring_enter(fd, 0, 0, IORING_ENTER_SQ_WAKEUP);

```

where sq_ring is a submission queue ring setup using the struct io_sqring_offsets described below.

Note that, when using a ring setup with IORING_SETUP_SQPOLL, you never directly call the io_uring_enter(2) system call. That is usually taken care of by liburing's io_uring_submit(3) function. It automatically determines if you are using polling mode or not and deals with when your program needs to call io_uring_enter(2) without you having to bother about it.

Note that while this may sound immediately appealing as an automatic "go faster" flag, evaluations should be done on a case-by-case basis to check if it makes sense for the application.

Before version 5.11 of the Linux kernel, to successfully use this feature, the application must register a set of files to be used for IO through io_uring_register(2) using the IORING_REGISTER_FILES opcode. Failure to do so will result in submitted IO being errored with EBADF. The presence of this feature can be detected by the IORING_FEAT_SQPOLL_NONFIXED feature flag. In version 5.11 and later, it is no longer necessary to register files to use this feature. 5.11 also allows using this as non-root, if the user has the CAP_SYS_NICE capability. In 5.13 this requirement was also relaxed, and no special privileges are needed for SQPOLL in newer kernels. Certain stable kernels older than 5.13 may also support unprivileged SQPOLL.

IORING_SETUP_SQ_AFF

If this flag is specified, then the poll thread will be bound to the cpu set in the sq_thread_cpu field of the struct io_uring_params. This flag is only meaningful when IORING_SETUP_SQPOLL is specified. When cgroup setting cpuset.cpus changes (typically in container environment), the bounded cpu set may be changed as well.

IORING_SETUP_CQSIZE

Create the completion queue with struct io_uring_params.cq_entries entries. The value must be greater than entries, and may be rounded up to the next power-of-two.

IORING_SETUP_CLAMP

If this flag is specified, and if entries exceeds IORING_MAX_ENTRIES, then entries will be clamped at IORING_MAX_ENTRIES. If the flag IORING_SETUP_CQSIZE is set, and if the value of struct io_uring_params.cq_entries exceeds IORING_MAX_CQ_ENTRIES, then it will be clamped at IORING_MAX_CQ_ENTRIES.

IORING_SETUP_ATTACH_WQ

This flag should be set in conjunction with struct io_uring_params.wq_fd being set to an existing io_uring ring file descriptor. When set, the io_uring instance being created will share the asynchronous worker thread backend of the specified io_uring ring, rather than create a new separate thread pool. Additionally the sq polling thread will be shared, if IORING_SETUP_SQPOLL is set.

IORING_SETUP_R_DISABLED

If this flag is specified, the io_uring ring starts in a disabled state. In this state, restrictions can be registered, but submissions are not allowed. See io_uring_register(2) for details on how to enable the ring. Available since 5.10.

IORING_SETUP_SUBMIT_ALL

Normally io_uring stops submitting a batch of requests, if one of these requests results in an error. This can cause submission of less than what is expected, if a request ends in error while being submitted. If the ring is created with this flag, io_uring_enter(2) will continue submitting requests even if it encounters an error submitting a request. CQEs are still posted for errored request regardless of whether or not this flag is set at ring creation time, the only difference is if the submit sequence is halted or continued when an error is observed. Available since 5.18.

IORING_SETUP_COOP_TASKRUN

By default, io_uring will interrupt a task running in userspace when a completion event comes in. This is to ensure that completions run in a timely manner. For a lot of use cases, this is overkill and can cause reduced performance from both the inter-processor interrupt used to do this, the kernel/user transition, the needless interruption of the tasks userspace activities, and reduced batching if completions come in at a rapid rate. Most applications don't need the forceful interruption, as the events are processed at any kernel/user transition. The exception are setups where the application uses multiple threads operating on the same ring, where the application waiting on completions isn't the one that submitted them. For most other use cases, setting this flag will improve performance. Available since 5.19.

IORING_SETUP_TASKRUN_FLAG

Used in conjunction with IORING_SETUP_COOP_TASKRUN or IORING_SETUP_DEFER_TASKRUN, this provides a flag, IORING_SQ_TASKRUN, which is set in the SQ ring flags whenever completions are pending that should be processed. liburing will check for this flag even when doing io_uring_peek_cqe(3) and enter the kernel to process them, and applications can do the same. This makes IORING_SETUP_TASKRUN_FLAG safe to use even when applications rely on a peek style operation on the CQ ring to see if anything might be pending to reap. Available since 5.19.

IORING_SETUP_SQE128

If set, io_uring will use 128-byte SQEs rather than the normal 64-byte sized variant. This is a requirement for using certain request types, as of 5.19 only the IORING_OP_URING_CMD passthrough command for NVMe passthrough needs this. Available since 5.19.

IORING_SETUP_CQE32

If set, io_uring will use 32-byte CQEs rather than the normal 16-byte sized variant. This is a requirement for using certain request types, as of 5.19 only the IORING_OP_URING_CMD passthrough command for NVMe passthrough needs this. Also see IORING_SETUP_CQE_MIXED for an alternative to this flag. Available since 5.19.

IORING_SETUP_SINGLE_ISSUER

A hint to the kernel that only a single task (or thread) will submit requests, which is used for internal optimisations. The submission task is either the task that created the ring, or if IORING_SETUP_R_DISABLED is specified then it is the task that enables the ring through io_uring_register(2). The kernel enforces this rule, failing requests with -EEXIST if the restriction is violated. Note that when IORING_SETUP_SQPOLL is set it is considered that the polling task is doing all submissions on behalf of the userspace and so it always complies with the rule disregarding how many userspace tasks do io_uring_enter(2). Available since 6.0.

IORING_SETUP_DEFER_TASKRUN

By default, io_uring will process all outstanding work at the end of any system call or thread interrupt. This can delay the application from making other progress. Setting this flag will hint to io_uring that it should defer work until an io_uring_enter(2) call with the IORING_ENTER_GETEVENTS flag set. This allows the application to request work to run just before it wants to process completions. This flag requires the IORING_SETUP_SINGLE_ISSUER flag to be set, and also enforces that the call to io_uring_enter(2) is called from the same thread that submitted requests. Note that if this flag is set then it is the application's responsibility to periodically trigger work (for example via any of the CQE waiting functions) or else completions may not be delivered. Available since 6.1.

IORING_SETUP_NO_MMAP

By default, io_uring allocates kernel memory that callers must subsequently mmap(2). If this flag is set, io_uring instead uses caller-allocated buffers; p->cq_off.user_addr must point to the memory for the sq/cq rings, and p->sq_off.user_addr must point to the memory for the sqes. Each allocation must be contiguous memory. Typically, callers should allocate this memory by using mmap(2) to allocate a huge page. If this flag is set, a subsequent attempt to mmap(2) the io_uring file descriptor will fail. Available since 6.5.

IORING_SETUP_REGISTERED_FD_ONLY

If this flag is set, io_uring will register the ring file descriptor, and return the registered descriptor index, without ever allocating an unregistered file descriptor. The caller will need to use IORING_REGISTER_USE_REGISTERED_RING when calling io_uring_register(2). This flag only makes sense when used alongside with IORING_SETUP_NO_MMAP, which also needs to be set. Available since 6.5.

IORING_SETUP_NO_SQARRAY

If this flag is set, entries in the submission queue will be submitted in order, wrapping around to the first entry after reaching the end of the queue. In other words, there will be no more indirection via the array of submission entries, and the queue will be indexed directly by the submission queue tail and the range of indexed represented by it modulo queue size. Subsequently, the user should not map the array of submission queue entries, and the corresponding offset in struct io_sqring_offsets will be set to zero. Available since 6.6.

IORING_SETUP_CQE_MIXED

If this flag is set, the ring supports posting both the normal 16b sized CQEs as well as the larger 32b CQEs. Normally a ring is setup to only allow posting of normal 16b CQEs, or if IORING_SETUP_CQE32 has been set, only 32b CQEs. With this flag, the kernel may post both types. If a 32b CQE is posted, the CQE flags member will have IORING_CQE_F_32 set to indicate that this CQE is of the larger type. The kernel may also set IORING_CQE_F_SKIP in the CQE flags member, in case it needs to post a filler 16b CQE. This will happen if a 32b CQE needs posting and the current CQ ring offset is such that the 32b CQE would wrap around. Applications should simply skip/ignore such CQEs, they contain no information and serve only as placeholder to facilitate advancing the CQ ring such that a large CQE can get posted. The use case of the IORING_SETUP_CQE_MIXED flag is to allow more efficient setups of workloads that may post both normal and large CQEs. Opcodes that previously required the use of IORING_SETUP_CQE32 may now use this flag instead, and potentially save some memory for the CQ ring. If used with liburing 2.12 or newer, the handling of variably sized CQEs is fully transparent. Available since 6.18.

IORING_SETUP_SQ_REWIND

If this flag is set, the kernel ignores the submission queue head and tail and instead fetches SQEs starting from index 0. The application places all SQEs at the beginning of the SQ ring before each submit call, and the sq_entries parameter to io_uring_enter(2) determines how many SQEs are submitted. This is a non-circular queue mode where the kernel always starts from the beginning.

This flag requires IORING_SETUP_NO_SQARRAY to be set. It is not compatible with IORING_SETUP_SQPOLL.

This mode helps keep SQEs hot in cache by always accessing the same memory locations at the start of the ring, which can improve performance for workloads that submit small batches frequently. Available since 7.0.

If no flags are specified, the io_uring instance is setup for interrupt driven I/O. I/O may be submitted using io_uring_enter(2) and can be reaped by polling the completion queue.

The resv array must be initialized to zero.

features is filled in by the kernel, which specifies various features supported by current kernel version.

IORING_FEAT_SINGLE_MMAP

If this flag is set, the two SQ and CQ rings can be mapped with a single mmap(2) call. The SQEs must still be allocated separately. This brings the necessary mmap(2) calls down from three to two. Available since kernel 5.4.

IORING_FEAT_NODROP

If this flag is set, io_uring supports almost never dropping completion events. A dropped event can only occur if the kernel runs out of memory, in which case you have worse problems than a lost event. Your application and others will likely get OOM killed anyway. If a completion event occurs and the CQ ring is full, the kernel stores the event internally until such a time that the CQ ring has room for more entries. In earlier kernels, if this overflow condition is entered, attempting to submit more IO would fail with the -EBUSY error value, if it can't flush the overflown events to the CQ ring. If this happens, the application must reap events from the CQ ring and attempt the submit again. If the kernel has no free memory to store the event internally it will be visible by an increase in the overflow value on the cqring. Available since kernel 5.5. Additionally io_uring_enter(2) will return -EBADR the next time it would otherwise sleep waiting for completions (since kernel 5.19).

IORING_FEAT_SUBMIT_STABLE

If this flag is set, applications can be certain that any data for async offload has been consumed when the kernel has consumed the SQE. Available since kernel 5.5.

IORING_FEAT_RW_CUR_POS

If this flag is set, applications can specify offset == -1 with IORING_OP_{READV,WRITEV}, IORING_OP_{READ,WRITE}_FIXED, and IORING_OP_{READ,WRITE} to mean current file position, which behaves like preadv2(2) and pwritev2(2) with offset == -1. It'll use (and update) the current file position. This obviously comes with the caveat that if the application has multiple reads or writes in flight, then the end result will not be as expected. This is similar to threads sharing a file descriptor and doing IO using the current file position. Available since kernel 5.6.

IORING_FEAT_CUR_PERSONALITY

If this flag is set, then io_uring guarantees that both sync and async execution of a request assumes the credentials of the task that called io_uring_enter(2) to queue the requests. If this flag isn't set, then requests are issued with the credentials of the task that originally registered the io_uring. If only one task is using a ring, then this flag doesn't matter as the credentials will always be the same. Note that this is the default behavior, tasks can still register different personalities through io_uring_register(2) with IORING_REGISTER_PERSONALITY and specify the personality to use in the sqe. Available since kernel 5.6.

IORING_FEAT_FAST_POLL

If this flag is set, then io_uring supports using an internal poll mechanism to drive data/space readiness. This means that requests that cannot read or write data to a file no longer need to be punted to an async thread for handling, instead they will begin operation when the file is ready. This is similar to doing poll + read/write in userspace, but eliminates the need to do so. If this flag is set, requests waiting on space/data consume a lot less resources doing so as they are not blocking a thread. Available since kernel 5.7.

IORING_FEAT_POLL_32BITS

If this flag is set, the IORING_OP_POLL_ADD command accepts the full 32-bit range of epoll based flags. Most notably EPOLLEXCLUSIVE which allows exclusive (waking single waiters) behavior. Available since kernel 5.9.

IORING_FEAT_SQPOLL_NONFIXED

If this flag is set, the IORING_SETUP_SQPOLL feature no longer requires the use of fixed files. Any normal file descriptor can be used for IO commands without needing registration. Available since kernel 5.11.

IORING_FEAT_EXT_ARG

If this flag is set, then the io_uring_enter(2) system call supports passing in an extended argument instead of just the sigset_t of earlier kernels. This. extended argument is of type struct io_uring_getevents_arg and allows the caller to pass in both a sigset_t and a timeout argument for waiting on events. The struct layout is as follows:

```
struct io_uring_getevents_arg {

    __u64 sigmask;

    __u32 sigmask_sz;

    __u32 pad;

    __u64 ts;
};
```

and a pointer to this struct must be passed in if IORING_ENTER_EXT_ARG is set in the flags for the enter system call. Available since kernel 5.11.

IORING_FEAT_NATIVE_WORKERS

If this flag is set, io_uring is using native workers for its async helpers. Previous kernels used kernel threads that assumed the identity of the original io_uring owning task, but later kernels will actively create what looks more like regular process threads instead. Available since kernel 5.12.

IORING_FEAT_RSRC_TAGS

If this flag is set, then io_uring supports a variety of features related to fixed files and buffers. In particular, it indicates that registered buffers can be updated in-place, whereas before the full set would have to be unregistered first. Available since kernel 5.13.

IORING_FEAT_CQE_SKIP

If this flag is set, then io_uring supports setting IOSQE_CQE_SKIP_SUCCESS in the submitted SQE, indicating that no CQE should be generated for this SQE if it executes normally. If an error happens processing the SQE, a CQE with the appropriate error value will still be generated. Available since kernel 5.17.

IORING_FEAT_LINKED_FILE

If this flag is set, then io_uring supports sane assignment of files for SQEs that have dependencies. For example, if a chain of SQEs are submitted with IOSQE_IO_LINK, then kernels without this flag will prepare the file for each link upfront. If a previous link opens a file with a known index, eg if direct descriptors are used with open or accept, then file assignment needs to happen post execution of that SQE. If this flag is set, then the kernel will defer file assignment until execution of a given request is started. Available since kernel 5.17.

IORING_FEAT_REG_REG_RING

If this flag is set, then io_uring supports calling io_uring_register(2) using a registered ring fd, via IORING_REGISTER_USE_REGISTERED_RING. Available since kernel 6.3.

IORING_FEAT_MIN_TIMEOUT

If this flag is set, then io_uring supports passing in a minimum batch wait timeout. See io_uring_submit_and_wait_min_timeout(3) for more details.

IORING_FEAT_RECVSEND_BUNDLE

If this flag is set, then io_uring supports bundled send and recv operations. See io_uring_prep_send_bundle(3) for more information. Also implies support for provided buffers in send operations.

The rest of the fields in the struct io_uring_params are filled in by the kernel, and provide the information necessary to memory map the submission queue, completion queue, and the array of submission queue entries. sq_entries specifies the number of submission queue entries allocated. sq_off describes the offsets of various ring buffer fields:

```
struct io_sqring_offsets {

    __u32 head;

    __u32 tail;

    __u32 ring_mask;

    __u32 ring_entries;

    __u32 flags;

    __u32 dropped;

    __u32 array;

    __u32 resv1;

    __u64 user_addr;
};
```

Taken together, sq_entries and sq_off provide all of the information necessary for accessing the submission queue ring buffer and the submission queue entry array. The submission queue can be mapped with a call like:

```
ptr = mmap(0, sq_off.array + sq_entries * sizeof(__u32),

           PROT_READ|PROT_WRITE, MAP_SHARED|MAP_POPULATE,

           ring_fd, IORING_OFF_SQ_RING);
```

where sq_off is the io_sqring_offsets structure, and ring_fd is the file descriptor returned from io_uring_setup(2). The addition of sq_off.array to the length of the region accounts for the fact that the ring is located at the end of the data structure. As an example, the ring buffer head pointer can be accessed by adding sq_off.head to the address returned from mmap(2):

```
head = ptr + sq_off.head;
```

The flags field is used by the kernel to communicate state information to the application. Currently, it is used to inform the application when a call to io_uring_enter(2) is necessary. See the documentation for the IORING_SETUP_SQPOLL flag above. The dropped member is incremented for each invalid submission queue entry encountered in the ring buffer.

The head and tail track the ring buffer state. The tail is incremented by the application when submitting new I/O, and the head is incremented by the kernel when the I/O has been successfully submitted. Determining the index of the head or tail into the ring is accomplished by applying a mask:

```
index = tail & ring_mask;
```

The array of submission queue entries is mapped with:

```
sqentries = mmap(0, sq_entries * sizeof(struct io_uring_sqe),

                 PROT_READ|PROT_WRITE, MAP_SHARED|MAP_POPULATE,

                 ring_fd, IORING_OFF_SQES);
```

The completion queue is described by cq_entries and cq_off shown here:

```
struct io_cqring_offsets {

    __u32 head;

    __u32 tail;

    __u32 ring_mask;

    __u32 ring_entries;

    __u32 overflow;

    __u32 cqes;

    __u32 flags;

    __u32 resv1;

    __u64 user_addr;
};
```

The completion queue is simpler, since the entries are not separated from the queue itself, and can be mapped with:

```
ptr = mmap(0, cq_off.cqes + cq_entries * sizeof(struct io_uring_cqe),

           PROT_READ|PROT_WRITE, MAP_SHARED|MAP_POPULATE, ring_fd,

           IORING_OFF_CQ_RING);
```

Closing the file descriptor returned by io_uring_setup(2) will free all resources associated with the io_uring context. Note that this may happen asynchronously within the kernel, so it is not guaranteed that resources are freed immediately.

## RETURN VALUE
io_uring_setup(2) returns a new file descriptor on success. The application may then provide the file descriptor in a subsequent mmap(2) call to map the submission and completion queues, or to the io_uring_register(2) or io_uring_enter(2) system calls.

On error, a negative error code is returned. The caller should not rely on errno variable.

## ERRORS
EFAULT

params is outside your accessible address space.

EINVAL

The resv array contains non-zero data, p.flags contains an unsupported flag, entries is out of bounds, IORING_SETUP_SQ_AFF was specified, but IORING_SETUP_SQPOLL was not, or IORING_SETUP_CQSIZE was specified, but io_uring_params.cq_entries was invalid. IORING_SETUP_REGISTERED_FD_ONLY was specified, but IORING_SETUP_NO_MMAP was not.

EMFILE

The per-process limit on the number of open file descriptors has been reached (see the description of RLIMIT_NOFILE in getrlimit(2)).

ENFILE

The system-wide limit on the total number of open files has been reached.

ENOMEM

Insufficient kernel resources are available.

EPERM

IORING_SETUP_SQPOLL was specified, but the effective user ID of the caller did not have sufficient privileges.

EPERM

/proc/sys/kernel/io_uring_disabled has the value 2, or it has the value 1 and the calling process does not hold the CAP_SYS_ADMIN capability or is not a member of /proc/sys/kernel/io_uring_group.

ENXIO

IORING_SETUP_ATTACH_WQ was set, but params.wq_fd did not refer to an io_uring instance or refers to an instance that is in the process of shutting down.

## SEE ALSO
io_uring_register(2), io_uring_enter(2)


package: libxfs-devel

title: ioctl_xfs_ag_geometry(2)

text:
# ioctl_xfs_ag_geometry(2)

## NAME
ioctl_xfs_ag_geometry - query XFS allocation group geometry information

## SYNOPSIS
\#include <xfs/xfs_fs.h>

int ioctl(int fd, XFS_IOC_AG_GEOMETRY, struct xfs_ag_geometry *arg);

## DESCRIPTION
This XFS ioctl retrieves the geometry information for a given allocation group. The geometry information is conveyed in a structure of the following form:

```
struct xfs_ag_geometry {
	uint32_t  ag_number;
	uint32_t  ag_length;
	uint32_t  ag_freeblks;
	uint32_t  ag_icount;
	uint32_t  ag_ifree;
	uint32_t  ag_sick;
	uint32_t  ag_checked;
	uint32_t  ag_flags;
	uint64_t  ag_reserved[12];
};
```

ag_number

The caller must set this field to the index of the allocation group that the caller wishes to learn about.

ag_length

The length of the allocation group is returned in this field, in units of filesystem blocks.

ag_freeblks

The number of free blocks in the allocation group is returned in this field, in units of filesystem blocks.

ag_icount

The number of inode records allocated in this allocation group is returned in this field.

ag_ifree

The number of unused inode records (of the space allocated) in this allocation group is returned in this field.

ag_flags

The caller can set this field to change the operational behavior of the ioctl. Currently no flags are defined, so this field must be zero.

ag_reserved

All reserved fields will be set to zero on return.

The fields ag_sick and ag_checked indicate the relative health of various allocation group metadata:

•

If a given sick flag is set in ag_sick, then that piece of metadata has been observed to be damaged. The same bit will be set in ag_checked.

•

If a given sick flag is set in ag_checked and is not set in ag_sick, then that piece of metadata has been checked and is not faulty.

•

If a given sick flag is not set in ag_checked, then no conclusion can be made.

The following flags apply to these fields:

XFS_AG_GEOM_SICK_SB

Allocation group superblock.

XFS_AG_GEOM_SICK_AGF

Free space header.

XFS_AG_GEOM_SICK_AGFL

Free space reserve list.

XFS_AG_GEOM_SICK_AGI

Inode header.

XFS_AG_GEOM_SICK_BNOBT or XFS_AG_GEOM_SICK_CNTBT

Free space btrees.

XFS_AG_GEOM_SICK_INOBT or XFS_AG_GEOM_SICK_FINOBT

Inode btrees.

XFS_AG_GEOM_SICK_RMAPBT

Reverse mapping btree.

XFS_AG_GEOM_SICK_REFCNTBT

Reference count btree.

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

EFSBADCRC

Metadata checksum validation failed while performing the query.

EFSCORRUPTED

Metadata corruption was encountered while performing the query.

EINVAL

The specified allocation group number is not valid for this filesystem.

EIO

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

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

## SEE ALSO
ioctl(2)

branch: sisyphus


title: ioctl_xfs_bulkstat(2)

text:
# ioctl_xfs_bulkstat(2)

## NAME
ioctl_xfs_bulkstat - query information for a batch of XFS inodes

## SYNOPSIS
\#include <xfs/xfs_fs.h>

int ioctl(int fd, XFS_IOC_BULKSTAT, struct xfs_bulkstat_req *arg);

## DESCRIPTION
Query stat information for a group of XFS inodes. This ioctl uses struct xfs_bulkstat_req to set up a bulk transfer from the kernel:

```
struct xfs_bulkstat_req {
	struct xfs_bulk_ireq    hdr;
	struct xfs_bulkstat     bulkstat[];
};
```

See below for the xfs_bulkstat structure definition.

```
struct xfs_bulk_ireq {
	uint64_t                ino;
	uint32_t                flags;
	uint32_t                icount;
	uint32_t                ocount;
	uint32_t                agno;
	uint64_t                reserved[5];
};
```

hdr.ino should be set to the number of the first inode for which the caller wants information; or zero to start with the first inode in the filesystem; or a special value if XFS_BULK_IREQ_SPECIAL is set in the flags field. Note that this is a different semantic than the lastip in the old FSBULKSTAT ioctl. After the call, this value will be set to the number of the next inode for which information could supplied. This sets up the next call for an iteration loop.

If the XFS_BULK_IREQ_SPECIAL flag is set in the flags field, the ino field is interpreted according to the following special values:

XFS_BULK_IREQ_SPECIAL_ROOT

Return stat information for the root directory inode.

hdr.flags is a bit set of operational flags:

XFS_BULK_IREQ_AGNO

If this is set, the call will only return results for the allocation group (AG) set in hdr.agno. If hdr.ino is set to zero, results will be returned starting with the first inode in the AG. This flag may not be set at the same time as the XFS_BULK_IREQ_SPECIAL flag.

XFS_BULK_IREQ_SPECIAL

If this is set, results will be returned for only the special inode specified in the hdr.ino field. This flag may not be set at the same time as the XFS_BULK_IREQ_AGNO flag.

XFS_BULK_IREQ_NREXT64

If this is set, data fork extent count is returned via bs_extents64 field and 0 is assigned to bs_extents. Otherwise, data fork extent count is returned via bs_extents field and bs_extents64 is assigned a value of 0. In the second case, bs_extents is set to (2^31 - 1) if data fork extent count is larger than 2^31. This flag may be set independently of whether other flags have been set.

XFS_BULK_IREQ_METADIR

Return metadata directory tree inodes in the stat output as well. The only fields that will be populated are bs_ino, bs_gen, bs_mode, bs_sick, and bs_checked. All other fields, notably bs_blksize, will be zero.

hdr.icount is the maximum number of records to return. This should be the size of the array that comes after the header.

hdr.ocount will be set to the number of records actually returned.

hdr.agno is the number of the allocation group (AG) for which we want results. If the XFS_BULK_IREQ_AGNO flag is not set, this field is ignored.

hdr.reserved must be set to zero.

bulkstat is an array of struct xfs_bulkstat which is described below. The array must have at least icount elements.

```
struct xfs_bulkstat {
	uint64_t                bs_ino;
	uint64_t                bs_size;
	uint64_t                bs_blocks;
	uint64_t                bs_xflags;
	uint64_t                bs_atime;
	uint64_t                bs_mtime;
	uint64_t                bs_ctime;
	uint64_t                bs_btime;
	uint32_t                bs_gen;
	uint32_t                bs_uid;
	uint32_t                bs_gid;
	uint32_t                bs_projectid;
	uint32_t                bs_atime_nsec;
	uint32_t                bs_mtime_nsec;
	uint32_t                bs_ctime_nsec;
	uint32_t                bs_btime_nsec;
	uint32_t                bs_blksize;
	uint32_t                bs_rdev;
	uint32_t                bs_cowextsize_blks;
	uint32_t                bs_extsize_blks;
	uint32_t                bs_nlink;
	uint32_t                bs_extents;
	uint32_t                bs_aextents;
	uint16_t                bs_version;
	uint16_t                bs_forkoff;
	uint16_t                bs_sick;
	uint16_t                bs_checked;
	uint16_t                bs_mode;
	uint16_t                bs_pad2;
	uint64_t                bs_extents64;
	uint64_t                bs_pad[6];
};
```

bs_ino is the inode number of this record.

bs_size is the size of the file, in bytes.

bs_blocks is the number of filesystem blocks allocated to this file, including metadata.

bs_xflags tell us what extended flags are set this inode. These flags are the same values as those defined in the XFS INODE FLAGS section of the ioctl_xfs_fsgetxattr(2) manpage.

bs_atime is the last time this file was accessed, in seconds.

bs_mtime is the last time the contents of this file were modified, in seconds.

bs_ctime is the last time this inode record was modified, in seconds.

bs_btime is the time this inode record was created, in seconds.

bs_gen is the generation number of the inode record.

bs_uid is the user id.

bs_gid is the group id.

bs_projectid is the the project id.

bs_atime_nsec is the nanoseconds component of the last time this file was accessed.

bs_mtime_nsec is the nanoseconds component of the last time the contents of this file were modified.

bs_ctime_nsec is the nanoseconds component of the last time this inode record was modified.

bs_btime_nsec is the nanoseconds component of the time this inode record was created.

bs_blksize is the size of a data block for this file, in units of bytes.

bs_rdev is the encoded device id if this is a special file.

bs_cowextsize_blks is the Copy on Write extent size hint for this file, in units of data blocks.

bs_extsize_blks is the extent size hint for this file, in units of data blocks.

bs_nlink is the number of hard links to this inode.

bs_extents is the number of storage mappings associated with this file's data.

bs_aextents is the number of storage mappings associated with this file's extended attributes.

bs_version is the version of this data structure. This will be set to XFS_BULKSTAT_VERSION_V5 by the kernel.

bs_forkoff is the offset of the attribute fork in the inode record, in bytes.

The fields bs_sick and bs_checked indicate the relative health of various allocation group metadata. Please see the section XFS INODE METADATA HEALTH REPORTING for more information.

bs_mode is the file type and mode.

bs_pad[7] is zeroed.

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

## XFS INODE METADATA HEALTH REPORTING
The online filesystem checking utility scans inode metadata and records what it finds in the kernel incore state. The following scheme is used for userspace to read the incore health status of an inode:

•

If a given sick flag is set in bs_sick, then that piece of metadata has been observed to be damaged. The same bit should be set in bs_checked.

•

If a given sick flag is set in bs_checked but is not set in bs_sick, then that piece of metadata has been checked and is not faulty.

•

If a given sick flag is not set in bs_checked, then no conclusion can be made.

The following flags apply to these fields:

XFS_BS_SICK_INODE

The inode's record itself.

XFS_BS_SICK_BMBTD

File data extent mappings.

XFS_BS_SICK_BMBTA

Extended attribute extent mappings.

XFS_BS_SICK_BMBTC

Copy on Write staging extent mappings.

XFS_BS_SICK_DIR

Directory information.

XFS_BS_SICK_XATTR

Extended attribute data.

XFS_BS_SICK_SYMLINK

Symbolic link target.

XFS_BS_SICK_PARENT

Parent pointers.

XFS_BS_SICK_DIRTREE

Directory is the source of corruption in the directory tree.

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

## SEE ALSO
ioctl(2), ioctl_xfs_fsgetxattr(2)


title: ioctl_xfs_commit_range(2)

text:
# ioctl_xfs_commit_range(2)

## NAME
ioctl_xfs_commit_range - conditionally exchange the contents of parts of two files ioctl_xfs_start_commit - prepare to exchange the contents of two files

## SYNOPSIS
\#include <sys/ioctl.h>

\#include <xfs/xfs_fs.h>

int ioctl(int file2_fd, XFS_IOC_START_COMMIT, struct xfs_commit_range *arg);

int ioctl(int file2_fd, XFS_IOC_COMMIT_RANGE, struct xfs_commit_range *arg);

## DESCRIPTION
Given a range of bytes in a first file file1_fd and a second range of bytes in a second file file2_fd, this ioctl(2) exchanges the contents of the two ranges if file2_fd passes certain freshness criteria.

Before exchanging the contents, the program must call the XFS_IOC_START_COMMIT ioctl to sample freshness data for file2_fd. If the sampled metadata does not match the file metadata at commit time, XFS_IOC_COMMIT_RANGE will return EBUSY.

Exchanges are atomic with regards to concurrent file operations. Implementations must guarantee that readers see either the old contents or the new contents in their entirety, even if the system fails.

The system call parameters are conveyed in structures of the following form:

```
struct xfs_commit_range {

    __s32    file1_fd;

    __u32    pad;

    __u64    file1_offset;

    __u64    file2_offset;

    __u64    length;

    __u64    flags;

    __u64    file2_freshness[5];
};
```

The field pad must be zero.

The fields file1_fd, file1_offset, and length define the first range of bytes to be exchanged.

The fields file2_fd, file2_offset, and length define the second range of bytes to be exchanged.

The field file2_freshness is an opaque field whose contents are determined by the kernel. These file attributes are used to confirm that file2_fd has not changed by another thread since the current thread began staging its own update.

Both files must be from the same filesystem mount. If the two file descriptors represent the same file, the byte ranges must not overlap. Most disk-based filesystems require that the starts of both ranges must be aligned to the file block size. If this is the case, the ends of the ranges must also be so aligned unless the XFS_EXCHANGE_RANGE_TO_EOF flag is set.

The field flags control the behavior of the exchange operation.

XFS_EXCHANGE_RANGE_TO_EOF

Ignore the length parameter. All bytes in file1_fd from file1_offset to EOF are moved to file2_fd, and file2's size is set to (file2_offset+(file1_length-file1_offset)). Meanwhile, all bytes in file2 from file2_offset to EOF are moved to file1 and file1's size is set to (file1_offset+(file2_length-file2_offset)).

XFS_EXCHANGE_RANGE_DSYNC

Ensure that all modified in-core data in both file ranges and all metadata updates pertaining to the exchange operation are flushed to persistent storage before the call returns. Opening either file descriptor with O_SYNC or O_DSYNC will have the same effect.

XFS_EXCHANGE_RANGE_FILE1_WRITTEN

Only exchange sub-ranges of file1_fd that are known to contain data written by application software. Each sub-range may be expanded (both upwards and downwards) to align with the file allocation unit. For files on the data device, this is one filesystem block. For files on the realtime device, this is the realtime extent size. This facility can be used to implement fast atomic scatter-gather writes of any complexity for software-defined storage targets if all writes are aligned to the file allocation unit.

XFS_EXCHANGE_RANGE_DRY_RUN

Check the parameters and the feasibility of the operation, but do not change anything.

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

EBADF

file1_fd is not open for reading and writing or is open for append-only writes; or file2_fd is not open for reading and writing or is open for append-only writes.

EBUSY

The file2 inode number and timestamps supplied do not match file2_fd.

EINVAL

The parameters are not correct for these files. This error can also appear if either file descriptor represents a device, FIFO, or socket. Disk filesystems generally require the offset and length arguments to be aligned to the fundamental block sizes of both files.

EIO

An I/O error occurred.

EISDIR

One of the files is a directory.

ENOMEM

The kernel was unable to allocate sufficient memory to perform the operation.

ENOSPC

There is not enough free space in the filesystem exchange the contents safely.

EOPNOTSUPP

The filesystem does not support exchanging bytes between the two files.

EPERM

file1_fd or file2_fd are immutable.

ETXTBSY

One of the files is a swap file.

EUCLEAN

The filesystem is corrupt.

EXDEV

file1_fd and file2_fd are not on the same mounted filesystem.

## CONFORMING TO
This API is XFS-specific.

## USE CASES
Several use cases are imagined for this system call. Coordination between multiple threads is performed by the kernel.

The first is a filesystem defragmenter, which copies the contents of a file into another file and wishes to exchange the space mappings of the two files, provided that the original file has not changed.

An example program might look like this:

```
int fd = open("/some/file", O_RDWR);
int temp_fd = open("/some", O_TMPFILE | O_RDWR);
struct stat sb;
struct xfs_commit_range args = {

    .flags = XFS_EXCHANGE_RANGE_TO_EOF,
};
/* gather file2's freshness information */
ioctl(fd, XFS_IOC_START_COMMIT, &args);
fstat(fd, &sb);
/* make a fresh copy of the file with terrible alignment to avoid reflink */
clone_file_range(fd, NULL, temp_fd, NULL, 1, 0);
clone_file_range(fd, NULL, temp_fd, NULL, sb.st_size - 1, 0);
/* commit the entire update */
args.file1_fd = temp_fd;
ret = ioctl(fd, XFS_IOC_COMMIT_RANGE, &args);
if (ret && errno == EBUSY)

    printf("file changed while defrag was underway\n");
```

The second is a data storage program that wants to commit non-contiguous updates to a file atomically. This program cannot coordinate updates to the file and therefore relies on the kernel to reject the COMMIT_RANGE command if the file has been updated by someone else. This can be done by creating a temporary file, calling FICLONE(2) to share the contents, and staging the updates into the temporary file. The FULL_FILES flag is recommended for this purpose. The temporary file can be deleted or punched out afterwards.

An example program might look like this:

```
int fd = open("/some/file", O_RDWR);
int temp_fd = open("/some", O_TMPFILE | O_RDWR);
struct xfs_commit_range args = {

    .flags = XFS_EXCHANGE_RANGE_TO_EOF,
};
/* gather file2's freshness information */
ioctl(fd, XFS_IOC_START_COMMIT, &args);
ioctl(temp_fd, FICLONE, fd);
/* append 1MB of records */
lseek(temp_fd, 0, SEEK_END);
write(temp_fd, data1, 1000000);
/* update record index */
pwrite(temp_fd, data1, 600, 98765);
pwrite(temp_fd, data2, 320, 54321);
pwrite(temp_fd, data2, 15, 0);
/* commit the entire update */
args.file1_fd = temp_fd;
ret = ioctl(fd, XFS_IOC_COMMIT_RANGE, &args);
if (ret && errno == EBUSY)

    printf("file changed before commit; will roll back\n");
```

## NOTES
Some filesystems may limit the amount of data or the number of extents that can be exchanged in a single call.

## SEE ALSO
ioctl(2)


title: ioctl_xfs_exchange_range(2)

text:
# ioctl_xfs_exchange_range(2)

## NAME
ioctl_xfs_exchange_range - exchange the contents of parts of two files

## SYNOPSIS
\#include <sys/ioctl.h>

\#include <xfs/xfs_fs.h>

int ioctl(int file2_fd, XFS_IOC_EXCHANGE_RANGE, struct xfs_exchange_range *arg);

## DESCRIPTION
Given a range of bytes in a first file file1_fd and a second range of bytes in a second file file2_fd, this ioctl(2) exchanges the contents of the two ranges.

Exchanges are atomic with regards to concurrent file operations. Implementations must guarantee that readers see either the old contents or the new contents in their entirety, even if the system fails.

The system call parameters are conveyed in structures of the following form:

```
struct xfs_exchange_range {

    __s32    file1_fd;

    __u32    pad;

    __u64    file1_offset;

    __u64    file2_offset;

    __u64    length;

    __u64    flags;
};
```

The field pad must be zero.

The fields file1_fd, file1_offset, and length define the first range of bytes to be exchanged.

The fields file2_fd, file2_offset, and length define the second range of bytes to be exchanged.

Both files must be from the same filesystem mount. If the two file descriptors represent the same file, the byte ranges must not overlap. Most disk-based filesystems require that the starts of both ranges must be aligned to the file block size. If this is the case, the ends of the ranges must also be so aligned unless the XFS_EXCHANGE_RANGE_TO_EOF flag is set.

The field flags control the behavior of the exchange operation.

XFS_EXCHANGE_RANGE_TO_EOF

Ignore the length parameter. All bytes in file1_fd from file1_offset to EOF are moved to file2_fd, and file2's size is set to (file2_offset+(file1_length-file1_offset)). Meanwhile, all bytes in file2 from file2_offset to EOF are moved to file1 and file1's size is set to (file1_offset+(file2_length-file2_offset)).

XFS_EXCHANGE_RANGE_DSYNC

Ensure that all modified in-core data in both file ranges and all metadata updates pertaining to the exchange operation are flushed to persistent storage before the call returns. Opening either file descriptor with O_SYNC or O_DSYNC will have the same effect.

XFS_EXCHANGE_RANGE_FILE1_WRITTEN

Only exchange sub-ranges of file1_fd that are known to contain data written by application software. Each sub-range may be expanded (both upwards and downwards) to align with the file allocation unit. For files on the data device, this is one filesystem block. For files on the realtime device, this is the realtime extent size. This facility can be used to implement fast atomic scatter-gather writes of any complexity for software-defined storage targets if all writes are aligned to the file allocation unit.

XFS_EXCHANGE_RANGE_DRY_RUN

Check the parameters and the feasibility of the operation, but do not change anything.

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

EBADF

file1_fd is not open for reading and writing or is open for append-only writes; or file2_fd is not open for reading and writing or is open for append-only writes.

EINVAL

The parameters are not correct for these files. This error can also appear if either file descriptor represents a device, FIFO, or socket. Disk filesystems generally require the offset and length arguments to be aligned to the fundamental block sizes of both files.

EIO

An I/O error occurred.

EISDIR

One of the files is a directory.

ENOMEM

The kernel was unable to allocate sufficient memory to perform the operation.

ENOSPC

There is not enough free space in the filesystem exchange the contents safely.

EOPNOTSUPP

The filesystem does not support exchanging bytes between the two files.

EPERM

file1_fd or file2_fd are immutable.

ETXTBSY

One of the files is a swap file.

EUCLEAN

The filesystem is corrupt.

EXDEV

file1_fd and file2_fd are not on the same mounted filesystem.

## CONFORMING TO
This API is XFS-specific.

## USE CASES
Several use cases are imagined for this system call. In all cases, application software must coordinate updates to the file because the exchange is performed unconditionally.

The first is a data storage program that wants to commit non-contiguous updates to a file atomically and coordinates write access to that file. This can be done by creating a temporary file, calling FICLONE(2) to share the contents, and staging the updates into the temporary file. The FULL_FILES flag is recommended for this purpose. The temporary file can be deleted or punched out afterwards.

An example program might look like this:

```
int fd = open("/some/file", O_RDWR);
int temp_fd = open("/some", O_TMPFILE | O_RDWR);
ioctl(temp_fd, FICLONE, fd);
/* append 1MB of records */
lseek(temp_fd, 0, SEEK_END);
write(temp_fd, data1, 1000000);
/* update record index */
pwrite(temp_fd, data1, 600, 98765);
pwrite(temp_fd, data2, 320, 54321);
pwrite(temp_fd, data2, 15, 0);
/* commit the entire update */
struct xfs_exchange_range args = {

    .file1_fd = temp_fd,

    .flags = XFS_EXCHANGE_RANGE_TO_EOF,
};
ioctl(fd, XFS_IOC_EXCHANGE_RANGE, &args);
```

The second is a software-defined storage host (e.g. a disk jukebox) which implements an atomic scatter-gather write command. Provided the exported disk's logical block size matches the file's allocation unit size, this can be done by creating a temporary file and writing the data at the appropriate offsets. It is recommended that the temporary file be truncated to the size of the regular file before any writes are staged to the temporary file to avoid issues with zeroing during EOF extension. Use this call with the FILE1_WRITTEN flag to exchange only the file allocation units involved in the emulated device's write command. The temporary file should be truncated or punched out completely before being reused to stage another write.

An example program might look like this:

```
int fd = open("/some/file", O_RDWR);
int temp_fd = open("/some", O_TMPFILE | O_RDWR);
struct stat sb;
int blksz;
fstat(fd, &sb);
blksz = sb.st_blksize;
/* land scatter gather writes between 100fsb and 500fsb */
pwrite(temp_fd, data1, blksz * 2, blksz * 100);
pwrite(temp_fd, data2, blksz * 20, blksz * 480);
pwrite(temp_fd, data3, blksz * 7, blksz * 257);
/* commit the entire update */
struct xfs_exchange_range args = {

    .file1_fd = temp_fd,

    .file1_offset = blksz * 100,

    .file2_offset = blksz * 100,

    .length       = blksz * 400,

    .flags        = XFS_EXCHANGE_RANGE_FILE1_WRITTEN |

                    XFS_EXCHANGE_RANGE_FILE1_DSYNC,
};
ioctl(fd, XFS_IOC_EXCHANGE_RANGE, &args);
```

## NOTES
Some filesystems may limit the amount of data or the number of extents that can be exchanged in a single call.

## SEE ALSO
ioctl(2)


title: ioctl_xfs_fsbulkstat(2)

text:
# ioctl_xfs_fsbulkstat(2)

## NAME
ioctl_xfs_fsbulkstat - query information for a batch of XFS inodes

## SYNOPSIS
\#include <xfs/xfs_fs.h>

int ioctl(int fd, XFS_IOC_FSBULKSTAT, struct xfs_fsop_bulkreq *arg);

int ioctl(int fd, XFS_IOC_FSBULKSTAT_SINGLE, struct xfs_fsop_bulkreq *arg);

## DESCRIPTION
Query stat information for a group of XFS inodes.

NOTE: This ioctl has been superseded. Please see the ioctl_xfs_bulkstat(2) manpage for information about its replacement.

These ioctls use struct xfs_fsop_bulkreq to set up a bulk transfer with the kernel:

```
struct xfs_fsop_bulkreq {
	__u64             *lastip;
	__s32             count;
	void              *ubuffer;
	__s32             *ocount;
};
```

lastip points to a value that will receive the number of the "last inode." This cannot be NULL. For FSBULKSTAT, this should be set to one less than the number of the first inode for which the caller wants information, or zero to start with the first inode in the filesystem. For FSBULKSTAT_SINGLE, this should be set to the number of the inode for which the caller wants information. After the call, this value will be set to the number of the last inode for which information was supplied. This field will not be updated if ocount is NULL.

count is the number of elements in the ubuffer array and therefore the number of inodes for which to return stat information. This value must be set to 1 for FSBULKSTAT_SINGLE.

ocount points to a value that will receive the number of records returned. If this value is NULL, then neither ocount nor lastip will be updated.

ubuffer points to a memory buffer into which inode stat information will be copied. This buffer must be an array of struct xfs_bstat which is described below. The array must have at least count elements.

```
struct xfs_bstat {
	__u64             bs_ino;
	__u16             bs_mode;
	__u16             bs_nlink;
	__u32             bs_uid;
	__u32             bs_gid;
	__u32             bs_rdev;
	__s32             bs_blksize;
	__s64             bs_size;
	struct xfs_bstime bs_atime;
	struct xfs_bstime bs_mtime;
	struct xfs_bstime bs_ctime;
	int64_t           bs_blocks;
	__u32             bs_xflags;
	__s32             bs_extsize;
	__s32             bs_extents;
	__u32             bs_gen;
	__u16             bs_projid_lo;
	__u16             bs_forkoff;
	__u16             bs_projid_hi;
	uint16_t          bs_sick;
	uint16_t          bs_checked;
	unsigned char     bs_pad[2];
	__u32             bs_cowextsize;
	__u32             bs_dmevmask;
	__u16             bs_dmstate;
	__u16             bs_aextents;
};
```

The structure members are as follows:

bs_ino is the inode number for this record.

bs_mode is the file type and mode.

bs_nlink is the number of hard links to this inode.

bs_uid is the user id.

bs_gid is the group id.

bs_rdev is the encoded device id if this is a special file.

bs_blksize is the size of a data block for this file, in units of bytes.

bs_size is the size of the file, in bytes.

bs_atime is the last time this file was accessed.

bs_mtime is the last time the contents of this file were modified.

bs_ctime is the last time this inode record was modified.

bs_blocks is the number of filesystem blocks allocated to this file, including metadata.

bs_xflags contains the extended flags that are set on this inode. These flags are the same values as those defined in the XFS INODE FLAGS section of the ioctl_xfs_fsgetxattr(2) manpage.

bs_extsize is the extent size hint for this file, in bytes.

bs_extents is the number of storage mappings associated with this file's data.

bs_gen is the generation number of the inode record.

bs_projid_lo is the lower 16-bits of the project id.

bs_forkoff is the offset of the attribute fork in the inode record, in bytes.

bs_projid_hi is the upper 16-bits of the project id.

bs_pad[6] is zeroed.

bs_cowextsize is the Copy on Write extent size hint for this file, in bytes.

bs_dmevmask is unused on Linux.

bs_dmstate is unused on Linux.

bs_aextents is the number of storage mappings associated with this file's extended attributes.

The fields bs_sick and bs_checked indicate the relative health of various inode metadata:

•

If a given sick flag is set in bs_sick, then that piece of metadata has been observed to be damaged. The same bit should be set in bs_checked.

•

If a given sick flag is set in bs_checked but is not set in bs_sick, then that piece of metadata has been checked and is not faulty.

•

If a given sick flag is not set in bs_checked, then no conclusion can be made.

The following flags apply to these fields:

XFS_BS_SICK_INODE

The inode's record itself.

XFS_BS_SICK_BMBTD

File data extent mappings.

XFS_BS_SICK_BMBTA

Extended attribute extent mappings.

XFS_BS_SICK_BMBTC

Copy on Write staging extent mappings.

XFS_BS_SICK_DIR

Directory information.

XFS_BS_SICK_XATTR

Extended attribute data.

XFS_BS_SICK_SYMLINK

Symbolic link target.

XFS_BS_SICK_PARENT

Parent pointers.

XFS_BS_SICK_DIRTREE

Directory is the source of corruption in the directory tree.

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

## SEE ALSO
ioctl(2), ioctl_xfs_fsgetxattr(2)


title: ioctl_xfs_fscounts(2)

summary: query XFS summary counter information

text:
# ioctl_xfs_fscounts(2)

## NAME
ioctl_xfs_fscounts - query XFS summary counter information

## SYNOPSIS
\#include <xfs/xfs_fs.h>

int ioctl(int fd, XFS_IOC_FSCOUNTS, struct xfs_fsop_counts *arg);

## DESCRIPTION
Query the raw filesystem summary counters. Unlike statvfs(3), the values returned here are the raw values, which do not reflect any alterations or limits set by project quotas. The counter information is conveyed in a structure of the following form:

```
struct xfs_fsop_counts {
	__u64   freedata;
	__u64   freertx;
	__u64   freeino;
	__u64   allocino;
};
```

The fields of this structure are as follows:

freedata is the number of free filesystem blocks on the data device.

freertx is the number of free extents on the realtime device.

freeino is the number of inode records that are not in use within the space that has been allocated for them.

allocino is the number of inode records for which space has been allocated.

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

EFSBADCRC

Metadata checksum validation failed while performing the query.

EFSCORRUPTED

Metadata corruption was encountered while performing the query.

EINVAL

The specified allocation group number is not valid for this filesystem.

EIO

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

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

## SEE ALSO
ioctl(2)


title: ioctl_xfs_fsgeometry(2)

text:
# ioctl_xfs_fsgeometry(2)

## NAME
ioctl_xfs_fsgeometry - report XFS filesystem layout and features

## SYNOPSIS
\#include <xfs/xfs_fs.h>

int ioctl(int fd, XFS_IOC_FSGEOMETRY, struct xfs_fsop_geom *arg);

int ioctl(int fd, XFS_IOC_FSGEOMETRY_V4, struct xfs_fsop_geom_v4 *arg);

int ioctl(int fd, XFS_IOC_FSGEOMETRY_V1, struct xfs_fsop_geom_v1 *arg);

## DESCRIPTION
Report the details of an XFS filesystem layout, features, and other descriptive items. This information is conveyed in a structure of the following form:

```
struct xfs_fsop_geom {
	__u32         blocksize;
	__u32         rtextsize;
	__u32         agblocks;
	__u32         agcount;
	__u32         logblocks;
	__u32         sectsize;
	__u32         inodesize;
	__u32         imaxpct;
	__u64         datablocks;
	__u64         rtblocks;
	__u64         rtextents;
	__u64         logstart;
	unsigned char uuid[16];
	__u32         sunit;
	__u32         swidth;
	__s32         version;
	__u32         flags;
	__u32         logsectsize;
	__u32         rtsectsize;
	__u32         dirblocksize;
	/* struct xfs_fsop_geom_v1 stops here. */
	__u32         logsunit;
	/* struct xfs_fsop_geom_v4 stops here. */
	__u32         sick;
	__u32         checked;
	__u64         rgextents;
	__u64	      rtstart;
	__u64         rtreserved;
	__u64         reserved[14];
};
```

blocksize is the size of a fundamental filesystem block, in bytes.

rtextsize is the size of an extent on the realtime volume, in bytes.

agblocks is the size of an allocation group, in units of filesystem blocks.

agcount is the number of allocation groups in the filesystem.

logblocks is the size of the log, in units of filesystem blocks.

sectsize is the smallest amount of data that can be written to the data device atomically, in bytes.

inodesize is the size of an inode record, in bytes.

imaxpct is the maximum percentage of the filesystem that can be allocated to inode record blocks.

datablocks is the size of the data device, in units of filesystem blocks.

rtblocks is the size of the realtime device, in units of filesystem blocks.

rtextents is the number of extents that can be allocated on the realtime device.

logstart is the start of the log, in units of filesystem blocks. If the filesystem has an external log, this will be zero.

uuid is the universal unique identifier of the filesystem.

sunit is what the filesystem has been told is the size of a RAID stripe unit on the underlying data device, in filesystem blocks.

swidth is what the filesystem has been told is the width of a RAID stripe on the underlying data device, in units of RAID stripe units.

version is the version of this structure. This value will be XFS_FSOP_GEOM_VERSION.

flags tell us what features are enabled on the filesystem. Refer to the section FILESYSTEM FEATURE FLAGS below for more information about each feature.

logsectsize is the smallest amount of data that can be written to the log device atomically, in bytes.

rtsectsize is the smallest amount of data that can be written to the realtime device atomically, in bytes.

dirblocksize is the size of directory blocks, in bytes.

logsunit is what the filesystem has been told is the size of a RAID stripe unit on the underlying log device, in filesystem blocks. This field is meaningful only if the flag XFS_FSOP_GEOM_FLAGS_LOGV2 is set.

The fields sick and checked indicate the relative health of various whole-filesystem metadata. Please see the section XFS METADATA HEALTH REPORTING for more details.

rgextents Is the number of RT extents in each rtgroup.

rtstart Start of the internal RT device in fsblocks. 0 if an external RT device is used. This field is meaningful only if the flag XFS_FSOP_GEOM_FLAGS_ZONED is set.

rtreserved The amount of space in the realtime section that is reserved for internal use by garbage collection and reorganization algorithms in fsblocks. This field is meaningful only if the flag XFS_FSOP_GEOM_FLAGS_ZONED is set.

reserved is set to zero.

## FILESYSTEM FEATURE FLAGS
Filesystem features are reported to userspace as a combination the following flags:

XFS_FSOP_GEOM_FLAGS_ATTR

Extended attributes are present.

XFS_FSOP_GEOM_FLAGS_NLINK

Files on this filesystem support up to 2^32 hard links. If this flag is not set, files on this filesystem support only up to 2^16 hard links.

XFS_FSOP_GEOM_FLAGS_QUOTA

Quotas are enabled.

XFS_FSOP_GEOM_FLAGS_IALIGN

Inodes are aligned for better performance.

XFS_FSOP_GEOM_FLAGS_DALIGN

Filesystem tries to align data block allocations to RAID stripe units for better performance.

XFS_FSOP_GEOM_FLAGS_SHARED

Unused.

XFS_FSOP_GEOM_FLAGS_EXTFLG

Filesystem supports unwritten extents.

XFS_FSOP_GEOM_FLAGS_DIRV2

Directories are in version 2 format and maintain free space data for better performance. Version 1 format directories are no longer supported.

XFS_FSOP_GEOM_FLAGS_LOGV2

Log uses the V2 format.

XFS_FSOP_GEOM_FLAGS_SECTOR

The log device has a sector size larger than 512 bytes.

XFS_FSOP_GEOM_FLAGS_ATTR2

Filesystem contains V2 extended attributes.

XFS_FSOP_GEOM_FLAGS_PROJID32

Project IDs can be as large as 2^32. If this flag is not set, the filesystem supports only 2^16 project IDs.

XFS_FSOP_GEOM_FLAGS_DIRV2CI

Case-insensitive lookups are supported on directories.

XFS_FSOP_GEOM_FLAGS_LAZYSB

On-disk superblock counters are updated only at unmount time.

XFS_FSOP_GEOM_FLAGS_V5SB

Metadata blocks are self describing and contain checksums.

XFS_FSOP_GEOM_FLAGS_FTYPE

Directories contain inode types in directory entries.

XFS_FSOP_GEOM_FLAGS_FINOBT

Filesystem maintains an index of free inodes.

XFS_FSOP_GEOM_FLAGS_SPINODES

Filesystem may allocate discontiguous inode chunks when free space is fragmented.

XFS_FSOP_GEOM_FLAGS_RMAPBT

Filesystem stores reverse mappings of blocks to owners.

XFS_FSOP_GEOM_FLAGS_REFLINK

Filesystem supports sharing blocks between files.

XFS_FSOP_GEOM_FLAGS_EXCHANGE_RANGE

Filesystem can exchange file contents atomically via XFS_IOC_EXCHANGE_RANGE.

XFS_FSOP_GEOM_FLAGS_METADIR

Filesystem contains a metadata directory tree.

XFS_FSOP_GEOM_FLAGS_ZONED

Filesystem uses the zoned allocator for the RT device.

## XFS METADATA HEALTH REPORTING
The online filesystem checking utility scans metadata and records what it finds in the kernel incore state. The following scheme is used for userspace to read the incore health status of the filesystem:

•

If a given sick flag is set in sick, then that piece of metadata has been observed to be damaged. The same bit should be set in checked.

•

If a given sick flag is set in checked but is not set in sick, then that piece of metadata has been checked and is not faulty.

•

If a given sick flag is not set in checked, then no conclusion can be made.

The following flags apply to these fields:

XFS_FSOP_GEOM_SICK_COUNTERS

Inode and space summary counters.

XFS_FSOP_GEOM_SICK_UQUOTA

User quota information.

XFS_FSOP_GEOM_SICK_GQUOTA

Group quota information.

XFS_FSOP_GEOM_SICK_PQUOTA

Project quota information.

XFS_FSOP_GEOM_SICK_RT_BITMAP

Free space bitmap for the realtime device.

XFS_FSOP_GEOM_SICK_RT_SUMMARY

Free space summary for the realtime device.

XFS_FSOP_GEOM_SICK_QUOTACHECK

Quota resource usage counters.

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

EIO

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

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

## SEE ALSO
ioctl(2)


title: ioctl_xfs_fsgetxattr(2)

summary: query information for an open file

text:
# ioctl_xfs_fsgetxattr(2)

## NAME
ioctl_xfs_fsgetxattr - query information for an open file

## SYNOPSIS
\#include <linux/fs.h>

int ioctl(int fd, XFS_IOC_FSGETXATTR, struct fsxattr *arg);

int ioctl(int fd, XFS_IOC_FSGETXATTRA, struct fsxattr *arg);

int ioctl(int fd, XFS_IOC_FSSETXATTR, struct fsxattr *arg);

## DESCRIPTION
Query or set additional attributes associated with files in various file systems. The attributes are conveyed in a structure of the form:

```
struct fsxattr {
	__u32         fsx_xflags;
	__u32         fsx_extsize;
	__u32         fsx_nextents;
	__u32         fsx_projid;
	__u32         fsx_cowextsize;
	unsigned char fsx_pad[8];
};
```

fsx_xflags are extended flags that apply to this file. Refer to the section XFS INODE FLAGS below for more information.

fsx_extsize is the preferred extent allocation size for data blocks mapped to this file, in units of bytes. If this value is zero, the filesystem will choose a default option, which is currently zero. If XFS_IOC_FSSETXATTR is called with XFS_XFLAG_EXTSIZE set in fsx_xflags and this field set to zero, the XFLAG will also be cleared.

fsx_nextents is the number of data extents in this file. If XFS_IOC_FSGETXATTRA was used, then this is the number of extended attribute extents in the file.

fsx_projid is the project ID of this file.

fsx_cowextsize is the preferred extent allocation size for copy on write operations targeting this file, in units of bytes. If this field is zero, the filesystem will choose a default option, which is currently 32 filesystem blocks. If XFS_IOC_FSSETXATTR is called with XFS_XFLAG_COWEXTSIZE set in fsx_xflags and this field set to zero, the XFLAG will also be cleared.

fsx_pad must be zeroed.

## XFS INODE FLAGS
This field can be a combination of the following:

XFS_XFLAG_REALTIME

The file is a realtime file. This bit can only be changed on a file when it has no allocated extents.

XFS_XFLAG_PREALLOC

The file has preallocated space.

XFS_XFLAG_IMMUTABLE

The file is immutable - it cannot be modified, deleted or renamed, no link can be created to this file and no data can be written to the file. Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE capability can set or clear this flag. If this flag is set before a XFS_IOC_FSSETXATTR call and would not be cleared by the call, then no other attributes can be changed and EPERM will be returned.

XFS_XFLAG_APPEND

The file is append-only - it can only be opened in append mode for writing. For directories, this means that files cannot be unlinked from this directory. Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE capability can set or clear this flag.

XFS_XFLAG_SYNC

All writes to the file are synchronous. If set on a directory and the /proc/sys/fs/xfs/inherit_sync tunable is set to 1, new files and subdirectories created in the directory will also have the flag set.

XFS_XFLAG_NOATIME

When the file is accessed, its atime record is not modified. If set on a directory and the /proc/sys/fs/xfs/inherit_noatime tunable is set to 1, new files and subdirectories created in the directory will also have the flag set.

XFS_XFLAG_NODUMP

The file should be skipped by backup utilities. If set on a directory and the /proc/sys/fs/xfs/inherit_nodump tunable is set to 1, new files and subdirectories created in the directory will also have the flag set.

XFS_XFLAG_RTINHERIT

Realtime inheritance bit - new files created in the directory will be automatically created as realtime files. If set on a directory, new subdirectories created in the directory will also have the inheritance flag set.

XFS_XFLAG_PROJINHERIT

Project inheritance bit - new files and directories created in this directory will inherit the project ID of this directory. If set on a directory, new subdirectories created in the directory will also have the inheritance flag set.

XFS_XFLAG_NOSYMLINKS

Disallows creation of symbolic links in the directory. This flag can only be set on a directory. If set on a directory and the /proc/sys/fs/xfs/inherit_nosymlinks tunable is set to 1, new files and subdirectories created in the directory will also have the flag set.

XFS_XFLAG_EXTSIZE

Extent size bit - if a basic extent size value is set on the file then the allocator will allocate in multiples of the set size for this file (see fsx_extsize below). The extent size can only be changed on a file when it has no allocated extents.

XFS_XFLAG_EXTSZINHERIT

Extent size inheritance bit - new files and directories created in the directory will inherit the extent size value (see fsx_extsize below) of the parent directory. New subdirectories created in the directory will inherit the extent size inheritance bit.

XFS_XFLAG_NODEFRAG

No defragment file bit - the file should be skipped during a defragmentation operation. If set on a directory and the /proc/sys/fs/xfs/inherit_nodefrag tunable is set to 1, new files and subdirectories created in the directory will also have the flag set.

XFS_XFLAG_FILESTREAM

Filestream allocator bit - allows a directory to reserve an allocation group for exclusive use by files created within that directory. Files being written in other directories will not use the same allocation group and so files within different directories will not interleave extents on disk. The reservation is only active while files are being created and written into the directory. If set on a directory, new files and subdirectories created in the directory will also have the flag set.

XFS_XFLAG_DAX

If the filesystem lives on directly accessible persistent memory, reads and writes to this file will go straight to the persistent memory, bypassing the page cache. If set on a directory, new files and subdirectories created in the directory will also have the flag set. This flag cannot be set on filesystems which have the reflink feature enabled.

XFS_XFLAG_COWEXTSIZE

Copy on Write Extent size bit - if a CoW extent size value is set on the file, the allocator will allocate extents for staging a copy on write operation in multiples of the set size for this file (see fsx_cowextsize below). If set on a directory, new files and subdirectories created in the directory will have both the flag and the CoW extent size value set.

XFS_XFLAG_HASATTR

The file has extended attributes associated with it.

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

EACCESS

Caller does not have sufficient access to change the attributes.

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.

EPERM

Caller did not have permission to change the attributes.

## CONFORMING TO
This API is implemented by the ext4, xfs, btrfs, and f2fs filesystems on the Linux kernel. Not all fields may be understood by filesystems other than xfs.

## SEE ALSO
ioctl(2), ioctl_iflags(2)


title: ioctl_xfs_fsinumbers(2)

text:
# ioctl_xfs_fsinumbers(2)

## NAME
ioctl_xfs_fsinumbers - extract a list of valid inode numbers from an XFS filesystem

## SYNOPSIS
\#include <xfs/xfs_fs.h>

int ioctl(int fd, XFS_IOC_FSINUMBERS, struct xfs_fsop_bulkreq *arg);

## DESCRIPTION
Queries inode allocation information from an XFS filesystem. It is intended to be called iteratively to obtain the entire set of inodes. These ioctls use struct xfs_fsop_bulkreq to set up a bulk transfer with the kernel:

```
struct xfs_fsop_bulkreq {
	__u64   *lastip;
	__s32   count;
	void    *ubuffer;
	__s32   *ocount;
};
```

lastip points to a value that will receive the number of the "last inode." This should be set to one less than the number of the first inode for which the caller wants information, or zero to start with the first inode in the filesystem. After the call, this value will be set to the number of the last inode for which information is supplied. This field will not be updated if ocount is NULL.

count is the number of elements in the ubuffer array and therefore the number of inode groups for which to return allocation information.

ocount points to a value that will receive the number of records returned. An output value of zero means that there are no more inode groups left to enumerate. If this value is NULL, then neither ocount nor lastip will be updated.

ubuffer points to a memory buffer where inode group information will be copied. This buffer must be an array of struct xfs_inogrp which is described below. The array must have at least count elements.

```
struct xfs_inogrp {
	__u64   xi_startino;
	__s32   xi_alloccount;
	__u64   xi_allocmask;
}
```

This structure describes inode usage information for a group of 64 consecutive inode numbers. The fields are as follows:

xi_startino is the first inode number of this group.

xi_alloccount is the number of bits that are set in xi_allocmask. This is the number of inodes allocated in this group.

xi_allocmask is a bitmask of inodes that are allocated in this inode group. The bitmask is 64 bits long, and the least significant bit corresponds to inode xi_startino.

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

## SEE ALSO
ioctl(2)


title: ioctl_xfs_getbmapx(2)

text:
# ioctl_xfs_getbmapx(2)

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

## SEE ALSO
ioctl(2)


title: ioctl_xfs_getparents(2)

summary: query XFS directory parent information

text:
# ioctl_xfs_getparents(2)

## NAME
ioctl_xfs_getparents - query XFS directory parent information

## SYNOPSIS
\#include <xfs/xfs_fs.h>

int ioctl(int fd, XFS_IOC_GETPARENTS, struct xfs_getparents *arg);

int ioctl(int fd, XFS_IOC_GETPARENTS_BY_HANDLE, struct xfs_getparents_by_handle *arg);

## DESCRIPTION
This command is used to retrieve the directory parent pointers of either the currently opened file or a file handle. Parent pointers point upwards in the directory tree from a child file towards a parent directories. Each entry in a parent directory must have a corresponding parent pointer in the child.

Calling programs should allocate a large memory buffer and initialize a header of the following form:

```
struct xfs_getparents {
	struct xfs_attrlist_cursor  gp_cursor;
	__u16                       gp_iflags;
	__u16                       gp_oflags;
	__u32                       gp_bufsize;
	__u64                       __pad;
	__u64                       gp_buffer;
};
struct xfs_getparents_by_handle {
	struct xfs_handle           gph_handle;
	struct xfs_getparents       gph_request;
};
```

The field gp_cursor tracks the progress of iterating through the parent pointers. Calling programs must initialize this to zero before the first system call and must not touch it after that.

The field gp_iflags control the behavior of the query operation and provide more information about the outcome of the operation. There are no input flags currently defined; this field must be zero.

The field gp_oflags contains information about the query itself. Possibly output flags are:

XFS_GETPARENTS_OFLAG_ROOT

The file queried was the root directory.

XFS_GETPARENTS_OFLAG_DONE

There are no more parent pointers to query.

The field __pad must be zero.

The field gp_bufsize should be set to the size of the buffer, in bytes.

The field gp_buffer should point to an output buffer for the parent pointer records.

Parent pointer records are returned in the following form:

```
struct xfs_getparents_rec {
	struct xfs_handle           gpr_parent;
	__u16                       gpr_reclen;
	char                        gpr_name[];
};
```

The field gpr_parent is a file handle that can be used to open the parent directory.

The field gpr_reclen will be set to the number of bytes used by this parent record.

The array gpr_name will be set to a NULL-terminated byte sequence representing the filename stored in the parent pointer. If the name is a zero-length string, the file queried has no parents.

## SAMPLE PROGRAM
Calling programs should allocate a large memory buffer, initialize the head structure to zeroes, set gp_bufsize to the size of the buffer, and call the ioctl. The XFS_GETPARENTS_OFLAG_DONE flag will be set in gp_flags when there are no more parent pointers to be read. The below code is an example of XFS_IOC_GETPARENTS usage:

```
#include <stdio.h>
#include <string.h>
#include <errno.h>
#include <xfs/linux.h>
#include <xfs/xfs.h>
#include <xfs/xfs_types.h>
#include <xfs/xfs_fs.h>
int main() {
	struct xfs_getparents gp = { };
	struct xfs_getparents_rec *gpr;
	int error, fd;
	gp.gp_buffer = (uintptr_t)malloc(65536);
	if (!gp.gp_buffer) {
		perror("malloc");
		return 1;
	}
	gp->gp_bufsize = 65536;
	fd = open("/mnt/test/foo.txt", O_RDONLY | O_CREAT);
	if (fd  == -1)
		return errno;
	do {
		error = ioctl(fd, XFS_IOC_GETPARENTS, gp);
		if (error)
			return error;
		for (gpr = xfs_getparents_first_rec(&gp);
		     gpr != NULL;
		     gpr = xfs_getparents_next_rec(&gp, gpr)) {
			if (gpr->gpr_name[0] == 0)
				break;
			printf("inode		= %llu\n",
					gpr->gpr_parent.ha_fid.fid_ino);
			printf("generation	= %u\n",
					gpr->gpr_parent.ha_fid.fid_gen);
			printf("name		= \"%s\"\n\n",
					gpr->gpr_name);
		}
	} while (!(gp.gp_flags & XFS_GETPARENTS_OFLAG_DONE));
	return 0;
}
```

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

EFSBADCRC

Metadata checksum validation failed while performing the query.

EFSCORRUPTED

Metadata corruption was encountered while performing the query.

EINVAL

One or more of the arguments specified is invalid.

EMSGSIZE

The record buffer was not large enough to store even a single record.

ENOMEM

Not enough memory to retrieve parent pointers.

EOPNOTSUPP

Repairs of the requested metadata object are not supported.

EROFS

Filesystem is read-only and a repair was requested.

ESHUTDOWN

Filesystem is shut down due to previous errors.

EIO

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

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

## SEE ALSO
ioctl(2)


title: ioctl_xfs_getresblks(2)

text:
# ioctl_xfs_getresblks(2)

## NAME
ioctl_xfs_getresblks - query and set XFS free space reservation information

## SYNOPSIS
\#include <xfs/xfs_fs.h>

int ioctl(int fd, XFS_IOC_GET_RESBLKS, struct xfs_fsop_resblks *arg);

int ioctl(int fd, XFS_IOC_SET_RESBLKS, struct xfs_fsop_resblks *arg);

## DESCRIPTION
Query or set the free space reservation information. These blocks are reserved by the filesystem as a final attempt to prevent metadata update failures due to insufficient space. Only the system administrator can use these ioctls, because overriding the defaults is extremely dangerous.

This functionality is intended only for use by XFS filesystem developers.

The reservation information is conveyed in a structure of the following form:

```
struct xfs_fsop_resblks {
	__u64  resblks;
	__u64  resblks_avail;
};
```

resblks is the number of blocks that the filesystem will try to maintain to prevent critical out of space situations.

resblks_avail is the number of reserved blocks remaining.

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

EFSBADCRC

Metadata checksum validation failed while performing the query.

EFSCORRUPTED

Metadata corruption was encountered while performing the query.

EINVAL

The specified allocation group number is not valid for this filesystem.

EIO

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

EPERM

Caller does not have permission to call this ioctl.

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

## SEE ALSO
ioctl(2)


title: ioctl_xfs_goingdown(2)

summary: shut down an XFS filesystem

text:
# ioctl_xfs_goingdown(2)

## NAME
ioctl_xfs_goingdown - shut down an XFS filesystem

## SYNOPSIS
\#include <xfs/xfs_fs.h>

int ioctl(int fd, XFS_IOC_GOINGDOWN, uint32_t flags);

## DESCRIPTION
Shuts down a live XFS filesystem. This is a software initiated hard shutdown and should be avoided whenever possible. After this call completes, the filesystem ill be totally unusable until the filesystem has been unmounted and remounted.

flags can be one of the following:

XFS_FSOP_GOING_FLAGS_DEFAULT

Flush all dirty data and metadata to disk, flush pending transactions to the log, and shut down.

XFS_FSOP_GOING_FLAGS_LOGFLUSH

Flush all pending metadata transactions to the log and shut down, leaving all dirty data unwritten.

XFS_FSOP_GOING_FLAGS_NOLOGFLUSH

Shut down immediately, without writing pending transactions or dirty data to disk.

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

EFSBADCRC

Metadata checksum validation failed while performing the query.

EFSCORRUPTED

Metadata corruption was encountered while performing the query.

EIO

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

EPERM

Caller did not have permission to shut down the filesystem.

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

## SEE ALSO
ioctl(2)


title: ioctl_xfs_health_fd_on_monitored_fs(2)

text:
# ioctl_xfs_health_fd_on_monitored_fs(2)

## NAME
ioctl_xfs_health_fd_on_monitored_fs - check if the given fd belongs to the same fs being monitored

## SYNOPSIS
\#include <xfs/xfs_fs.h>

int ioctl(int healthmon_fd, XFS_IOC_HEALTH_FD_ON_MONITORED_FS, struct xfs_health_file_on_monitored_fs *arg);

## DESCRIPTION
This XFS healthmon fd ioctl asks the kernel driver if the file descriptor passed in via arg points to a file on the same filesystem that is being monitored by healthmon_fd. The file descriptor is conveyed in a structure of the following form:

```
struct xfs_health_file_on_monitored_fs {
	__s32 fd;
	__u32 flags;
};
```

The field flags must be zero.

The field fd is a descriptor of an open file.

The argument healthmon_fd must be a file opened via the XFS_IOC_HEALTH_MONITOR ioctl.

## RETURN VALUE
On error, -1 is returned, and errno is set to indicate the error. If the file descriptor points to a file on the same filesystem that is being monitored, 0 is returned.

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

ESTALE

The open file is not on the same filesystem that is being monitored.

EINVAL

One or more of the arguments specified is invalid.

EBADF

arg.fd does not refer to an open file.

EFAULT

The arg structure could not be copied into the kernel.

ENOTTY

healthmon_fd is not a XFS health monitoring file.

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

## SEE ALSO
ioctl_xfs_health_monitor(2)


title: ioctl_xfs_health_monitor(2)

text:
# ioctl_xfs_health_monitor(2)

## NAME
ioctl_xfs_health_monitor - read filesystem health events from the kernel

## SYNOPSIS
\#include <xfs/xfs_fs.h>

int ioctl(int dest_fd, XFS_IOC_HEALTH_MONITOR, struct xfs_health_monitor *arg);

## DESCRIPTION
This XFS ioctl asks the kernel driver to create a pseudo-file from which information about adverse filesystem health events can be read. This new file will be installed into the file descriptor table of the calling process as a read-only file, and will have the close-on-exec flag set.

The specific behaviors of this health monitor file are requested via a structure of the following form:

```
struct xfs_health_monitor {
	__u64 flags;
	__u8  format;
	__u8  pad[23];
};
```

The field pad must be zero.

The field format controls the format of the event data that can be read:

XFS_HEALTH_MONITOR_FMT_V0

Event data will be presented in discrete objects of type struct xfs_health_monitor_event. See below for more information.

The field flags control the behavior of the monitor.

XFS_HEALTH_MONITOR_VERBOSE

Return all health events, including affirmations of healthy metadata.

## RETURN VALUE
On error, -1 is returned, and errno is set to indicate the error. Otherwise, the return value is a new file descriptor.

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

EEXIST

Health monitoring is already active for this filesystem.

EPERM

The caller does not have permission to open a health monitor. Calling programs must have administrative capability, run in the initial user namespace, and the fd passed to ioctl must be the root directory of an XFS filesystem.

EINVAL

One or more of the arguments specified is invalid.

EFAULT

The argument could not be copied into the kernel.

ENOMEM

There was not sufficient memory to construct the health monitor.

## EVENT FORMAT
Calling programs retrieve XFS health events by calling read(2) on the returned file descriptor. The read buffer must be large enough to hold at least one event object. Partial objects will not be returned; instead, a short read will occur.

Events will be returned in the following format:

```
struct xfs_health_monitor_event {
	__u32	domain;
	__u32	type;
	__u64	time_ns;
	union {
		struct xfs_health_monitor_lost lost;
		struct xfs_health_monitor_fs fs;
		struct xfs_health_monitor_group group;
		struct xfs_health_monitor_inode inode;
		struct xfs_health_monitor_shutdown shutdown;
		struct xfs_health_monitor_media media;
		struct xfs_health_monitor_filerange filerange;
	} e;
	__u64	pad[2];
};
```

The field time_ns records the timestamp at which the health event was generated, in units of nanoseconds since the Unix epoch.

The field pad will be zero.

The field domain indicates the scope of the filesystem affected by the event:

XFS_HEALTH_MONITOR_DOMAIN_MOUNT

The entire filesystem is affected.

XFS_HEALTH_MONITOR_DOMAIN_FS

Metadata concerning the entire filesystem is affected. Details are available through the fs field.

XFS_HEALTH_MONITOR_DOMAIN_AG

Metadata concerning a specific allocation group is affected. Details are available through the group field.

XFS_HEALTH_MONITOR_DOMAIN_RTGROUP

Metadata concerning a specific realtime allocation group is affected. Details are available through the group field.

XFS_HEALTH_MONITOR_DOMAIN_INODE

File metadata is affected. Details are available through the inode field.

XFS_HEALTH_MONITOR_DOMAIN_DATADEV

The main data volume is affected. Details are available through the media field.

XFS_HEALTH_MONITOR_DOMAIN_RTDEV

The realtime volume is affected. Details are available through the media field.

XFS_HEALTH_MONITOR_DOMAIN_LOGDEV

The external log is affected. Details are available through the media field.

XFS_HEALTH_MONITOR_DOMAIN_FILERANGE

File data is affected. Details are available through the filerange field.

The field type indicates what was affected by a health event:

The following types apply to events from the MOUNT domain.

XFS_HEALTH_MONITOR_TYPE_RUNNING

This filesystem health monitor is now running.

XFS_HEALTH_MONITOR_TYPE_LOST

Health events were lost. Details are available through the lost field.

XFS_HEALTH_MONITOR_TYPE_UNMOUNT

The filesystem is being unmounted.

XFS_HEALTH_MONITOR_TYPE_SHUTDOWN

The filesystem has shut down due to problems. Details are available through the shutdown field.

The following three types apply to events from the FS, AG, RTGROUP, and INODE domains.

XFS_HEALTH_MONITOR_TYPE_SICK

Filesystem metadata has been scanned by online fsck and found to be corrupt.

XFS_HEALTH_MONITOR_TYPE_CORRUPT

A metadata corruption problem was encountered during a filesystem operation outside of fsck.

XFS_HEALTH_MONITOR_TYPE_HEALTHY

Filesystem metadata has either been scanned by online fsck and found to be in good condition, or it has been repaired to good condition.

The following type applies to events from the DATADEV, RTDEV, and LOGDEV domains.

XFS_HEALTH_MONITOR_TYPE_MEDIA_ERROR

A media error has been observed on one of the storage devices that can be attached to an XFS filesystem.

The following types apply to events from the FILERANGE domain.

XFS_HEALTH_MONITOR_TYPE_BUFREAD

An attempt to read (or readahead) from a file failed with an I/O error.

XFS_HEALTH_MONITOR_TYPE_BUFWRITE

An attempt to write dirty data to storage failed with an I/O error.

XFS_HEALTH_MONITOR_TYPE_DIOREAD

A direct read of file data from storage failed with an I/O error.

XFS_HEALTH_MONITOR_TYPE_DIOWRITE

A direct write of file data to storage failed with an I/O error.

XFS_HEALTH_MONITOR_TYPE_DATALOST

A latent media error was discovered on the storage backing part of this file.

The union e contains further details about the health event:

The kernel will use no more than 32KiB of memory per monitoring file to queue health events. If this limit is exceeded, an event will be generated to describe how many events were lost:

```
struct xfs_health_monitor_lost {
	__u64	count;
};
```

The count field records the number of events lost.

If whole-filesystem metadata experiences a health event, the exact type of that metadata is recorded as follows:

```
struct xfs_health_monitor_fs {
	__u32	mask;
};
```

The mask field will contain XFS_FSOP_GEOM_SICK_* flags that are documented in the ioctl_xfs_fsgeometry(2) manual page.

If an allocation group (realtime or data) experiences a health event, the exact type and location of the metadata is recorded as follows:

```
struct xfs_health_monitor_group {
	__u32	mask;
	__u32	gno;
};
```

The mask field will contain XFS_AG_SICK_* flags that are documented in the ioctl_xfs_ag_geometry(2) manual page, or the XFS_RTGROUP_SICK_* flags that are documented by the ioctl_xfs_rtgroup_geometry(2) manual page.

The gno field will contain the group number.

If a file experiences a health event, the exact type and handle to the file is recorded as follows:

```
struct xfs_health_monitor_inode {
	__u32	mask;
	__u32	gen;
	__u64	ino;
};
```

The mask field will contain XFS_BS_SICK_* flags that are documented by the ioctl_xfs_bulkstat(2) manual page.

The ino and gen fields describe a handle to the affected file.

If the filesystem shuts down abnormally, the exact reasons are recorded as follows:

```
struct xfs_health_monitor_shutdown {
	__u32	reasons;
};
```

The reasons field is a combination of the following values:

XFS_HEALTH_SHUTDOWN_META_IO_ERROR

Metadata I/O errors were encountered.

XFS_HEALTH_SHUTDOWN_LOG_IO_ERROR

Log I/O errors were encountered.

XFS_HEALTH_SHUTDOWN_FORCE_UMOUNT

The filesystem was forcibly shut down by an administrator.

XFS_HEALTH_SHUTDOWN_CORRUPT_INCORE

In-memory metadata are corrupt.

XFS_HEALTH_SHUTDOWN_CORRUPT_ONDISK

On-disk metadata are corrupt.

XFS_HEALTH_SHUTDOWN_DEVICE_REMOVED

Storage devices were removed.

If a media error is discovered on the storage device, the exact location is recorded as follows:

```
struct xfs_health_monitor_media {
	__u64	daddr;
	__u64	bbcount;
};
```

The daddr and bbcount fields describe the range of the storage that were lost. Both are provided in units of 512-byte blocks.

If a problem is discovered with regular file data, the handle of the file and the exact range of the file are recorded as follows:

```
struct xfs_health_monitor_filerange {
	__u64	pos;
	__u64	len;
	__u64	ino;
	__u32	gen;
	__u32	error;
};
```

The ino and gen fields describe a handle to the affected file. The pos and len fields describe the range of the file data that are affected. Both are provided in units of bytes.

The error field describes the error that occurred. See the errno(3) manual page for more information.

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

## SEE ALSO
ioctl_xfs_health_fd_on_monitored_fs(2)