Documentation Archive Developer
Search
ADC Home > Reference Library > Reference > Mac OS X > Mac OS X Man Pages

 

This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

For more information about the manual page format, see the manual page for manpages(5).



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 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 supported
     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.
     The I/O policy can have the following values:

     IOPOL_DEFAULT    This is the default I/O policy for the first process and
                      every new created thread.

     IOPOL_NORMAL     I/Os with NORMAL policy are called NORMAL I/Os.  They
                      are handled by the system using best-effort.

     IOPOL_THROTTLE   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.

     IOPOL_PASSIVE    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 indirectly
                      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 IOPOL_DEFAULT, the I/O policy of the current
     process is used; if the I/O policy of the current thread is not
     IOPOL_DEFAULT, 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 IOPOL_DEFAULT, 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:

           Process I/O Policy      Thread I/O Policy      I/O Policy
           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 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. manual.
                        ual.

SEE ALSO
     nice(3), getpriority(2), setpriority(2), renice(8)

HISTORY
     The getiopolicy_np() and setiopolicy_np() function call first appeared in
     Mac OS X 10.5 (Leopard) .

BSD                              July 18, 2006                             BSD