setiopolicy_np man page on Darwin

Man page or keyword search:  
man Server   23457 pages
apropos Keyword Search (all sections)
Output format
Darwin logo
[printable version]

getiopolicy_np(3)	 BSD 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 I/O type is specified in the argument iotype.	The currently sup‐
     ported I/O type is IOPOL_TYPE_DISK, which means the I/O policy for I/Os
     to local disks can be get or set.	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, but not including remote volumes mounted through
     networks (AFP, SMB, NFS, etc) or disk images residing on remote volumes.

     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.
     Policy can have the following values:

     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 pol‐
		       icy 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 pri‐
		       ority 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 issu‐
		       ing 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 pas‐
		       sive 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 throt‐
     tleable 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 pol‐
     icy 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.

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 man‐
			ual.

NOTES
     The thread or process with a throttleable I/O policy enabled will be gen‐
     erally 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 avail‐
     able 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 consis‐
     tency guarantees provided to contiguous writes, this can not be done
     automatically for large writes.  If a thread or process with a throt‐
     tleable 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 sys‐
     tem 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) .

BSD				April 30, 2013				   BSD
[top]

List of man pages available for Darwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net