git.saurik.com Git - apple/libc.git/blame_incremental

... / ...

Commit	Line	Data
	1	.Dd July 18, 2006
	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 policy 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
	26	The I/O type is specified in the argument
	27	.Fa iotype .
	28	The currently supported I/O type is
	29	.Dv IOPOL_TYPE_DISK ,
	30	which means the I/O policy for I/Os to local disks can be get or set. I/Os to
	31	local disks are I/Os sent to the media without going through a network,
	32	including I/Os to internal and external hard drives, optical media in internal
	33	and external drives, flash drives, floppy disks, ram disks, and mounted disk
	34	images which reside on these media, but not including remote volumes mounted
	35	through networks (AFP, SMB, NFS, etc) or disk images residing on remote volumes.
	36	.Pp
	37	The scope that the I/O policy takes effect is specified in the argument
	38	.Fa scope
	39	as follows:
	40	.Bl -tag -width IOPOL_SCOPE_PROCESS
	41	.It IOPOL_SCOPE_PROCESS
	42	The I/O policy of all I/Os issued by the current process is get or set.
	43	.It IOPOL_SCOPE_THREAD
	44	The I/O policy of all I/Os issued by the current thread is get or set.
	45	.El
	46	.Pp
	47	In
	48	.Fn getiopolicy_np ,
	49	the I/O policy of the given I/O type and scope is returned. In
	50	.Fn setiopolicy_np ,
	51	the argument
	52	.Fa policy
	53	is an integer which contains the new I/O policy to be set for the given I/O
	54	type and scope. The I/O policy can have the following values:
	55	.Bl -tag -width IOPOL_PASSIVEXX
	56	.It IOPOL_DEFAULT
	57	This is the default I/O policy for the first process and every new created thread.
	58	.It IOPOL_NORMAL
	59	I/Os with NORMAL policy are called NORMAL I/Os. They are handled by the
	60	system using best-effort.
	61	.It IOPOL_THROTTLE
	62	I/Os with THROTTLE policy are called THROTTLE I/Os. If a THROTTLE I/O request
	63	occurs within a small time window (usually a fraction of a second) of another
	64	NORMAL I/O request, the thread that issues the THROTTLE I/O is forced to sleep
	65	for a certain interval. This slows down the thread that issues the THROTTLE I/O
	66	so that NORMAL I/Os can utilize most of the disk I/O bandwidth.
	67	.It IOPOL_PASSIVE
	68	The PASSIVE I/Os are a special type of NORMAL I/O that are processed the same as
	69	NORMAL I/Os but are ignored by the THROTTLE I/Os so that the threads issuing
	70	THROTTLE I/Os are not slowed down by PASSIVE I/Os. The PASSIVE I/O policy is
	71	useful for server type applications. The I/Os generated by these applications
	72	are called passive I/Os because these I/Os are caused directly or indirectly by
	73	the I/O requests they receive from client applications. For example, when an
	74	image file is mounted by DiskImages, DiskImages generate passive I/Os.
	75	DiskImages should mark these I/Os using the PASSIVE I/O policy so that when
	76	client applications that issue THROTTLE I/Os access the volume managed by
	77	DiskImages, these client applications will not be slowed down by the I/Os
	78	generated by DiskImages.
	79	.El
	80	.Pp
	81	The I/O policy of a new created process is inherited from its parent
	82	process. The I/O policy of an I/O request depends on the I/O policy of
	83	both the current thread and the current process. If the I/O policy of the
	84	current thread is IOPOL_DEFAULT, the I/O policy of the current process is
	85	used; if the I/O policy of the current thread is not IOPOL_DEFAULT, the
	86	I/O policy of the current thread overrides the I/O policy of the current
	87	process; if the I/O policy of the current process is IOPOL_DEFAULT, the
	88	policy of I/Os issued by this process is NORMAL. For example, given the
	89	following thread and process I/O policy in the first two columns, the I/O
	90	policy of all I/Os issued by the thread is given in the third column:
	91	.Bl -column "Process I/O ScopeXXX" "Thread I/O ScopeXXX" "I/O Policy" -offset indent
	92	.It Sy "Process I/O Policy Thread I/O Policy I/O Policy"
	93	.It "DEFAULT DEFAULT NORMAL"
	94	.It "DEFAULT PASSIVE PASSIVE"
	95	.It "THROTTLE DEFAULT THROTTLE"
	96	.It "THROTTLE PASSIVE PASSIVE"
	97	.It "PASSIVE NORMAL NORMAL"
	98	.El
	99	.Pp
	100	The thread or process with THROTTLE I/O policy enabled may be slowed down when
	101	it issues reads, but will not be slowed down when it issues writes.
	102	If it issues far more writes than reads (e.g., an application
	103	downloading large amounts of data through the network), these writes compete with the
	104	normal I/Os of other processes and may have an adverse effect on the I/O
	105	throughput or latency of those processes.
	106	.Pp
	107	.Sh RETURN VALUES
	108	The
	109	.Fn getiopolicy_np
	110	call returns the I/O policy of the given I/O type and scope. If error
	111	happens, -1 is returned. The
	112	.Fn setiopolicy_np
	113	call returns 0 if there is no error, or -1 if there is an error. When error
	114	happens, the error code is stored in the external variable
	115	.Fa errno .
	116	.Sh ERRORS
	117	.Fn Getiopolicy_np
	118	and
	119	.Fn setiopolicy_np
	120	will fail if:
	121	.Bl -tag -width Er
	122	.It Bq Er EINVAL
	123	Io_type or scope is not one of the values defined in this manual.
	124	.El
	125	.Pp
	126	In addition to the errors indicated above,
	127	.Fn setiopolicy_np
	128	will fail if:
	129	.Bl -tag -width Er
	130	.It Bq Er EINVAL
	131	Policy is not one of the values defined in this manual.
	132	.El
	133	.Sh SEE ALSO
	134	.Xr nice 3 ,
	135	.Xr getpriority 2 ,
	136	.Xr setpriority 2 ,
	137	.Xr renice 8
	138	.Sh HISTORY
	139	The
	140	.Fn getiopolicy_np
	141	and
	142	.Fn setiopolicy_np
	143	function call first appeared in Mac OS X 10.5 (Leopard) .