--- name: "getiopolicy_np" section: "3" platform: "macos" package: "xnu" version: "12377.121.6" release: "macOS 26.5" platforms: ["macos"] url: "https://new.carta.tech/getiopolicy_np" --- # getiopolicy\_np(3) manipulate the I/O policy of a process or thread ## NAME **getiopolicy\_np,** **setiopolicy\_np** – manipulate the I/O policy of a process or thread ## LIBRARY Standard C Library (libc, -lc) ## SYNOPSIS **#include \** *int*\ **getiopolicy\_np**(*int iotype*, *int scope*); *int*\ **setiopolicy\_np**(*int iotype*, *int scope*, *int policy*); ## DESCRIPTION The **getiopolicy\_np**() and **setiopolicy\_np**() functions are provided to get or set the I/O policies of the current process or the current thread. The policy of the I/O of the given type *iotype* can be get or set for the given *scope*. The scope that the I/O policy takes effect is specified in the argument *scope* as follows: - IOPOL\_SCOPE\_PROCESS The I/O policy of all I/Os issued by the current process is get or set. - IOPOL\_SCOPE\_THREAD The I/O policy of all I/Os issued by the current thread is get or set. In **getiopolicy\_np**(), the I/O policy of the given I/O type and scope is returned. In **setiopolicy\_np**(), the argument *policy* is an integer which contains the new I/O policy to be set for the given I/O type and scope. The I/O type is specified in the argument *iotype*. The currently supported I/O types are as follows: - IOPOL\_TYPE\_DISK This can mean either the I/O policy for I/Os to local disks or to remote volumes. I/Os to local disks are I/Os sent to the media without going through a network, including I/Os to internal and external hard drives, optical media in internal and external drives, flash drives, floppy disks, ram disks, and mounted disk images which reside on these media. I/Os to remote volumes are I/Os that require network activity to complete the operation. This is currently only supported for remote volumes mounted by SMB or AFP. IOPOL\_TYPE\_DISK supports following values for *policy:* - IOPOL\_IMPORTANT I/Os with the IMPORTANT policy are unrestricted. This policy should only be used for I/Os that are critical to system responsiveness. This is the default I/O policy for new threads. - IOPOL\_STANDARD The STANDARD policy is for work requested by the user, but that is not the user's current focus. I/Os with this policy may be delayed slightly to allow IMPORTANT I/Os to complete quickly. - IOPOL\_UTILITY The UTILITY policy is for short-running background work. I/Os with this policy are throttled to prevent a significant impact on the latency of IMPORTANT and STANDARD I/Os. - IOPOL\_THROTTLE The THROTTLE policy is for long-running I/O intensive background work, such as backups, search indexing, or file synchronization. I/Os with this policy will be throttled to avoid impacting performance of higher priority I/Os. - IOPOL\_PASSIVE The PASSIVE I/Os are a special type of I/O that are ignored by the other policies so that the threads issuing lower priority I/Os are not slowed down by PASSIVE I/Os. The PASSIVE I/O policy is useful for server type applications. The I/Os generated by these applications are called passive I/Os because these I/Os are caused directly or indirectly by the I/O requests they receive from client applications. For example, when an image file is mounted by DiskImages, DiskImages generate passive I/Os. DiskImages should mark these I/Os using the PASSIVE I/O policy so that when client applications that access the volume managed by DiskImages, these client applications will not be slowed down by the I/Os generated by DiskImages. I/Os with the STANDARD, UTILITY, and THROTTLE policies are called throttleable I/Os and are of decreasing priority. If a throttleable request occurs within a small time window of a request of higher priority, the thread that issued the throttleable I/O is forced to a sleep for a short period. (Both this window and the sleep period are dependent on the policy of the throttleable I/O.) This slows down the thread that issues the throttleable I/O so that higher-priority I/Os can complete with low-latency and receive a greater share of the disk bandwidth. Furthermore, an IMPORTANT I/O request may bypass a previously issued throttleable I/O request in kernel or driver queues and be sent to the device first. In some circumstances, very large throttleable I/O requests will be broken into smaller requests which are then issued serially. The I/O policy of a newly created process is inherited from its parent process. The I/O policy of an I/O request is the lowest priority policy of the current thread and the current process. - IOPOL\_TYPE\_VFS\_ATIME\_UPDATES This *iotype* lets users change the access time updates policy for the files accessed by the current thread or process. IOPOL\_TYPE\_VFS\_ATIME\_UPDATES supports the following values for *policy:* - IOPOL\_ATIME\_UPDATES\_OFF The ATIME\_UPDATES\_OFF policy turns off access time updation for files accessed. This policy is useful for applications which access a large number of files to reduce the metadata I/O writes. - IOPOL\_ATIME\_UPDATES\_DEFAULT This is the default I/O policy for new threads. Like with IOPOL\_TYPE\_DISK, the I/O policy of a newly created process is inherited from its parent process. Access time updates are turned off if the I/O policy is set to IOPOL\_ATIME\_UPDATES\_OFF for the current thread or current process. - IOPOL\_TYPE\_VFS\_MATERIALIZE\_DATALESS\_FILES This *iotype* lets users change the materialization policy for dataless files accessed by the current thread or process. IOPOL\_TYPE\_VFS\_MATERIALIZE\_DATALESS\_FILES supports the following values for *policy:* - IOPOL\_MATERIALIZE\_DATALESS\_FILES\_DEFAULT Selects the default materialization policy. For IOPOL\_SCOPE\_THREAD, all accesses by the current thread will follow the process policy. For IOPOL\_SCOPE\_PROCESS, all accesses will follow the system default policy (IOPOL\_MATERIALIZE\_DATALESS\_FILES\_OFF). - IOPOL\_MATERIALIZE\_DATALESS\_FILES\_OFF Disables materialization of dataless files by the current thread or process. - IOPOL\_MATERIALIZE\_DATALESS\_FILES\_ON Enables materialization of dataless files by the current thread or process. New processes inherit the policy of their parent process. - IOPOL\_TYPE\_VFS\_DISALLOW\_RW\_FOR\_O\_EVTONLY This *iotype* lets users changes the file access modes accessed by the current process. IOPOL\_TYPE\_VFS\_DISALLOW\_RW\_FOR\_O\_EVTONLY supports the following values for *policy:* - IOPOL\_VFS\_DISALLOW\_RW\_FOR\_O\_EVTONLY\_ON Disallows read and write access modes for files that the current process opens with O\_EVTONLY flag. This policy is immutable once enabled. - IOPOL\_VFS\_DISALLOW\_RW\_FOR\_O\_EVTONLY\_DEFAULT This is the default I/O policy for the current process. New processes inherit the policy of their parent process. ## RETURN VALUES The **getiopolicy\_np**() call returns the I/O policy of the given I/O type and scope. If error happens, -1 is returned. The **setiopolicy\_np**() call returns 0 if there is no error, or -1 if there is an error. When error happens, the error code is stored in the external variable *errno*. ## ERRORS **getiopolicy\_np**() and **setiopolicy\_np**() will fail if: - \[EINVAL\] Io\_type or scope is not one of the values defined in this manual. In addition to the errors indicated above, **setiopolicy\_np**() will fail if: - \[EINVAL\] Policy is not one of the values defined in this manual. ## NOTES The thread or process with a throttleable I/O policy enabled will be generally prevented from having an adverse effect on the throughput or latency of higher priority I/Os of other processes. However, there are a few considerations that users of the throttleable I/O policies should keep in mind: Consider using the F\_NOCACHE [fcntl(2)](/fcntl/2.md) command to prevent caching when using a throttleable I/O policy. This will reduce contention for available caches with IMPORTANT I/O. Large read requests will automatically be broken up into smaller requests to avoid stalling IMPORTANT I/O requests. However, due to the consistency guarantees provided to contiguous writes, this can not be done automatically for large writes. If a thread or process with a throttleable I/O policy enabled will be issuing large writes, consider the use of the F\_SINGLE\_WRITER [fcntl(2)](/fcntl/2.md) command. This will indicate to the system that there is only one thread writing to the file and allow automatic division of large writes. Write-heavy throttleable I/O workloads may fill a drive's track (write) cache. Subsequent higher priority writes must then wait for enough of the track cache to be flushed before they can continue. If the writes issued as throttleable I/O are small and not contiguous, many seeks may be incurred before space is available for a subsequent higher priority write. Issuers of throttleable I/O should attempt to issue their writes sequentially or to locations in a single small area of the drive (i.e. different positions in the same file) to ensure good spacial locality. The F\_FULLFSYNC [fcntl(2)](/fcntl/2.md) command can cause very long system-wide IO stalls; use this command only if absolutely necessary. ## SEE ALSO [nice(3)](/nice/3.md), [getpriority(2)](/getpriority/2.md), [setpriority(2)](/setpriority/2.md), [fcntl(2)](/fcntl/2.md), [open(2)](/open/2.md), [renice(8)](/renice/8.md) ## HISTORY The **getiopolicy\_np**() and **setiopolicy\_np**() function call first appeared in Mac OS X 10.5 (Leopard) .