getiopolicy_np(3) Library Functions Manual getiopolicy_np(3)
NAME
getiopolicy_np, setiopolicy_np – manipulate the I/O policy of a process
or thread
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <sys/resource.h>
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) 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) 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) command can cause very long system-wide IO
stalls; use this command only if absolutely necessary.
SEE ALSO
nice(3), getpriority(2), setpriority(2), fcntl(2), open(2), renice(8)
HISTORY
The getiopolicy_np() and setiopolicy_np() function call first appeared in
Mac OS X 10.5 (Leopard) .
macOS 15.2 February 11, 2019 macOS 15.2