Manual Pages for UNIX Darwin command on man setiopolicy

Manual Pages for UNIX Darwin command on man setiopolicy_np

getiopolicynp(3) BSD Library Functions Manual getiopolicynp(3)

NAME

ggeettiiooppoolliiccyynnpp,, sseettiiooppoolliiccyynnpp - manipulate the I/O policy of a process

or thread LLIIBBRRAARRYY

Standard C Library (libc, -lc)

SYNOPSIS

##iinncclluuddee <>

int ggeettiiooppoolliiccyynnpp(int iotype, int scope); int sseettiiooppoolliiccyynnpp(int iotype, int scope, int policy);

DESCRIPTION

The ggeettiiooppoolliiccyynnpp() and sseettiiooppoolliiccyynnpp() functions are provided to get or set the I/O policy 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 IOPOLTYPEDISK, 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: IOPOLSCOPEPROCESS The I/O policy of all I/Os issued by the current process is get or set. IOPOLSCOPETHREAD The I/O policy of all I/Os issued by the current thread is get or set. In ggeettiiooppoolliiccyynnpp(), the I/O policy of the given I/O type and scope is returned. In sseettiiooppoolliiccyynnpp(), 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 policy can have the following values: IOPOLDEFAULT This is the default I/O policy for the first process and every new created thread. IOPOLNORMAL I/Os with NORMAL policy are called NORMAL I/Os. They

are handled by the system using best-effort.

IOPOLTHROTTLE I/Os with THROTTLE policy are called THROTTLE I/Os. If a THROTTLE I/O request occurs within a small time window (usually a fraction of a second) of another NORMAL I/O request, the thread that issues the THROTTLE I/O is forced to sleep for a certain interval. This slows down the thread that issues the THROTTLE I/O so that NORMAL I/Os can utilize most of the disk I/O bandwidth. IOPOLPASSIVE The PASSIVE I/Os are a special type of NORMAL I/O that are processed the same as NORMAL I/Os but are ignored by the THROTTLE I/Os so that the threads issuing THROTTLE 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 indi-

rectly 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 issue THROTTLE I/Os access the volume managed by DiskImages, these client applications will not be slowed down by the I/Os generated by DiskImages. The I/O policy of a new created process is inherited from its parent process. The I/O policy of an I/O request depends on the I/O policy of both the current thread and the current process. If the I/O policy of the current thread is IOPOLDEFAULT, the I/O policy of the current process is used; if the I/O policy of the current thread is not IOPOLDEFAULT, the I/O policy of the current thread overrides the I/O policy of the current process; if the I/O policy of the current process is IOPOLDEFAULT, the policy of I/Os issued by this process is NORMAL. For example, given the following thread and process I/O policy in the first two columns, the I/O policy of all I/Os issued by the thread is given in the third column: PPrroocceessss II//OO PPoolliiccyy TThhrreeaadd II//OO PPoolliiccyy II//OO PPoolliiccyy DEFAULT DEFAULT NORMAL DEFAULT PASSIVE PASSIVE THROTTLE DEFAULT THROTTLE THROTTLE PASSIVE PASSIVE PASSIVE NORMAL NORMAL The thread or process with THROTTLE I/O policy enabled may be slowed down when it issues reads, but will not be slowed down when it issues writes. If it issues far more writes than reads (e.g., an application downloading large amounts of data through the network), these writes compete with the normal I/Os of other processes and may have an adverse effect on the I/O throughput or latency of those processes.

RETURN VALUES

The ggeettiiooppoolliiccyynnpp() call returns the I/O policy of the given I/O type

and scope. If error happens, -1 is returned. The sseettiiooppoolliiccyynnpp() 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. EERRRROORRSS GGeettiiooppoolliiccyynnpp() and sseettiiooppoolliiccyynnpp() will fail if: [EINVAL] Iotype or scope is not one of the values defined in this manual. In addition to the errors indicated above, sseettiiooppoolliiccyynnpp() will fail if:

[EINVAL] Policy is not one of the values defined in this man-

ual.