1.Dd February 11, 2019 2.Dt getiopolicy_np 3 3.Os 4.Sh NAME 5.Nm getiopolicy_np, setiopolicy_np 6.Nd manipulate the I/O policy of a process or thread 7.Sh LIBRARY 8.Lb libc 9.Sh SYNOPSIS 10.In sys/resource.h 11.Ft int 12.Fn getiopolicy_np "int iotype" "int scope" 13.Ft int 14.Fn setiopolicy_np "int iotype" "int scope" "int policy" 15.Sh DESCRIPTION 16The 17.Fn getiopolicy_np 18and 19.Fn setiopolicy_np 20functions are provided to get or set the I/O policies of the current process 21or the current thread. The policy of the I/O of the given type 22.Fa iotype 23can be get or set for the given 24.Fa scope . 25.Pp 26The scope that the I/O policy takes effect is specified in the argument 27.Fa scope 28as follows: 29.Bl -tag -width IOPOL_SCOPE_PROCESS 30.It IOPOL_SCOPE_PROCESS 31The I/O policy of all I/Os issued by the current process is get or set. 32.It IOPOL_SCOPE_THREAD 33The I/O policy of all I/Os issued by the current thread is get or set. 34.El 35.Pp 36In 37.Fn getiopolicy_np , 38the I/O policy of the given I/O type and scope is returned. In 39.Fn setiopolicy_np , 40the argument 41.Fa policy 42is an integer which contains the new I/O policy to be set for the given I/O 43type and scope. 44.Pp 45The I/O type is specified in the argument 46.Fa iotype . 47The currently supported I/O types are as follows: 48.Bl -tag -width F1 49.It IOPOL_TYPE_DISK 50This can mean either the I/O policy for I/Os to local disks or to 51remote volumes. 52I/Os to local disks are I/Os sent to the media without going through a network, 53including I/Os to internal and external hard drives, optical media in internal 54and external drives, flash drives, floppy disks, ram disks, and mounted disk 55images which reside on these media. 56I/Os to remote volumes are I/Os that require network activity to complete the 57operation. 58This is currently only supported for remote volumes mounted by SMB or AFP. 59.Pp 60IOPOL_TYPE_DISK supports following values for 61.Fa policy: 62.Bl -tag -width IOPOL_PASSIVEXXX 63.It IOPOL_IMPORTANT 64I/Os with the IMPORTANT policy are unrestricted. This policy should only be 65used for I/Os that are critical to system responsiveness. 66This is the default I/O policy for new threads. 67.It IOPOL_STANDARD 68The STANDARD policy is for work requested by the user, but that is not the 69user's current focus. I/Os with this policy may be delayed slightly to allow 70IMPORTANT I/Os to complete quickly. 71.It IOPOL_UTILITY 72The UTILITY policy is for short-running background work. I/Os with this policy 73are throttled to prevent a significant impact on the latency of IMPORTANT and 74STANDARD I/Os. 75.It IOPOL_THROTTLE 76The THROTTLE policy is for long-running I/O intensive background work, such as 77backups, search indexing, or file synchronization. I/Os with this policy will 78be throttled to avoid impacting performance of higher priority I/Os. 79.It IOPOL_PASSIVE 80The PASSIVE I/Os are a special type of I/O that are ignored by the other 81policies so that the threads issuing lower priority I/Os are not slowed down by 82PASSIVE I/Os. The PASSIVE I/O policy is useful for server type applications. 83The I/Os generated by these applications are called passive I/Os because these 84I/Os are caused directly or indirectly by the I/O requests they receive from 85client applications. For example, when an image file is mounted by DiskImages, 86DiskImages generate passive I/Os. DiskImages should mark these I/Os using the 87PASSIVE I/O policy so that when client applications that access the volume 88managed by DiskImages, these client applications will not be slowed down by the 89I/Os generated by DiskImages. 90.El 91.Pp 92I/Os with the STANDARD, UTILITY, and THROTTLE policies are called throttleable 93I/Os and are of decreasing priority. If a throttleable request occurs within a 94small time window of a request of higher priority, the thread that issued the 95throttleable I/O is forced to a sleep for a short period. (Both this window and 96the sleep period are dependent on the policy of the throttleable I/O.) This 97slows down the thread that issues the throttleable I/O so that higher-priority 98I/Os can complete with low-latency and receive a greater share of the disk 99bandwidth. Furthermore, an IMPORTANT I/O request may bypass a previously issued 100throttleable I/O request in kernel or driver queues and be sent to the device 101first. In some circumstances, very large throttleable I/O requests will be 102broken into smaller requests which are then issued serially. 103.Pp 104The I/O policy of a newly created process is inherited from its parent 105process. The I/O policy of an I/O request is the lowest priority 106policy of the current thread and the current process. 107.It IOPOL_TYPE_VFS_ATIME_UPDATES 108This 109.Fa iotype 110lets users change the access time updates policy for the files accessed 111by the current thread or process. 112.Pp 113IOPOL_TYPE_VFS_ATIME_UPDATES supports the following values for 114.Fa policy: 115.Bl -tag -width IOPOL_ATIME_UPDATES_DEFAULT 116.It IOPOL_ATIME_UPDATES_OFF 117The ATIME_UPDATES_OFF policy turns off access time updation for files accessed. 118This policy is useful for applications which access a large number of files 119to reduce the metadata I/O writes. 120.It IOPOL_ATIME_UPDATES_DEFAULT 121This is the default I/O policy for new threads. 122.El 123.Pp 124Like with IOPOL_TYPE_DISK, the I/O policy of a newly created process is 125inherited from its parent process. Access time updates are turned off if the 126I/O policy is set to IOPOL_ATIME_UPDATES_OFF for the current thread or current 127process. 128.It IOPOL_TYPE_VFS_MATERIALIZE_DATALESS_FILES 129This 130.Fa iotype 131lets users change the materialization policy for dataless files accessed 132by the current thread or process. 133.Pp 134IOPOL_TYPE_VFS_MATERIALIZE_DATALESS_FILES supports the following values for 135.Fa policy: 136.Bl -tag -width IOPOL_MATERIALIZE_DATALESS 137.It IOPOL_MATERIALIZE_DATALESS_FILES_DEFAULT 138Selects the default materialization policy. 139For IOPOL_SCOPE_THREAD, all accesses by the current thread will follow the 140process policy. 141For IOPOL_SCOPE_PROCESS, all accesses will follow the system default 142policy 143.Pq IOPOL_MATERIALIZE_DATALESS_FILES_OFF . 144.It IOPOL_MATERIALIZE_DATALESS_FILES_OFF 145Disables materialization of dataless files by the current thread or 146process. 147.It IOPOL_MATERIALIZE_DATALESS_FILES_ON 148Enables materialization of dataless files by the current thread or 149process. 150.El 151.Pp 152New processes inherit the policy of their parent process. 153.El 154.Sh RETURN VALUES 155The 156.Fn getiopolicy_np 157call returns the I/O policy of the given I/O type and scope. If error 158happens, -1 is returned. The 159.Fn setiopolicy_np 160call returns 0 if there is no error, or -1 if there is an error. When error 161happens, the error code is stored in the external variable 162.Fa errno . 163.Sh ERRORS 164.Fn getiopolicy_np 165and 166.Fn setiopolicy_np 167will fail if: 168.Bl -tag -width Er 169.It Bq Er EINVAL 170Io_type or scope is not one of the values defined in this manual. 171.El 172.Pp 173In addition to the errors indicated above, 174.Fn setiopolicy_np 175will fail if: 176.Bl -tag -width Er 177.It Bq Er EINVAL 178Policy is not one of the values defined in this manual. 179.El 180.Sh NOTES 181The thread or process with a throttleable I/O policy enabled will be generally 182prevented from having an adverse effect on the throughput or latency of higher 183priority I/Os of other processes. 184However, there are a few considerations that users of the throttleable I/O 185policies should keep in mind: 186.Pp 187Consider using the 188.Dv F_NOCACHE 189.Xr fcntl 2 190command to prevent caching when using a throttleable I/O policy. 191This will reduce contention for available caches with IMPORTANT I/O. 192.Pp 193Large read requests will automatically be broken up into smaller requests 194to avoid stalling IMPORTANT I/O requests. 195However, due to the consistency guarantees provided to contiguous writes, 196this can not be done automatically for large writes. 197If a thread or process with a throttleable I/O policy enabled will be issuing 198large writes, consider the use of the 199.Dv F_SINGLE_WRITER 200.Xr fcntl 2 201command. 202This will indicate to the system that there is only one thread writing to 203the file and allow automatic division of large writes. 204.Pp 205Write-heavy throttleable I/O workloads may fill a drive's track (write) cache. 206Subsequent higher priority writes must then wait for enough of the track cache 207to be flushed before they can continue. 208If the writes issued as throttleable I/O are small and not contiguous, many 209seeks may be incurred before space is available for a subsequent higher 210priority write. 211Issuers of throttleable I/O should attempt to issue their writes sequentially 212or to locations in a single small area of the drive (i.e. different 213positions in the same file) to ensure good spacial locality. 214.Pp 215The 216.Dv F_FULLFSYNC 217.Xr fcntl 2 218command can cause very long system-wide IO stalls; use this command only if absolutely necessary. 219.Sh SEE ALSO 220.Xr nice 3 , 221.Xr getpriority 2 , 222.Xr setpriority 2 , 223.Xr fcntl 2 , 224.Xr open 2 , 225.Xr renice 8 226.Sh HISTORY 227The 228.Fn getiopolicy_np 229and 230.Fn setiopolicy_np 231function call first appeared in Mac OS X 10.5 (Leopard) . 232