[apple/xnu.git] / bsd / man / man3 / getiopolicy_np.3

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