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