grio_reserve_fs(3X)                                        grio_reserve_fs(3X)


NAME
     grio_reserve_fs - request a guaranteed rate I/O reservation on a file
     system

SYNOPSIS
     #include <grio.h>
     int grio_reserve_fs( dev_t fs_dev, grio_resv_t *griorp);

DESCRIPTION
     grio_reserve_fs tries to obtain the I/O-rate guarantee specified by the
     griorp structure on the file system built on the device specified by
     fs_dev.

     The contents of the structure pointed to by griorp includes the following
     members:

     gr_start
          Start time of the guarantee in seconds since January 1, 1970.

     gr_duration
          Duration of the guarantee in seconds.

     gr_optime
          The length of the rate guarantee time quantum in microseconds.

     gr_opsize
          The amount of data guaranteed to be read/written within the time
          quantum.

     gr_stream_id
          This is the stream identifier returned by the routine when a rate
          guarantee has been established.

     gr_flags
          The flags in this field determine the characteristics of the rate
          guarantee.  The following flags are defined:

          PROC_PRIVATE_GUAR
                           Only the calling process can use the rate
                           guarantee. If cannot be transferred to other
                           processes.

          PROC_SHARE_GUAR  The rate guarantee can be transferred to other
                           processes.

          FIXED_ROTOR_GUAR Obtain a "rotor" type of guarantee and do not allow
                           the rotoration slot to change once it has been
                           established. (this is also known as a VOD
                           reservation)


          SLIP_ROTOR_GUAR  This is the same type of rate guarantee as
                           FIXED_ROTOR_GUAR except that the system will allow
                           the process's rotation slot to change if necessary.

          NON_ROTOR_GUAR   Obtain an ordinary type of rate guarantee (non-
                           rotor).

          REALTIME_SCHED_GUAR
                           Use realtime scheduling to satisfy the rate
                           guarantee. The process will be suspended if it
                           tries to perform I/O at a rate greater than its
                           guarantee.If not specified, the default behavior is
                           to allow the process to exceed its guaranteed rate,
                           if there is available device bandwidth.

          NON_SCHED_GUAR   Do not enforce the I/O rate scheduling. It is
                           assumed that the calling process will regulate the
                           rate at which I/O requests are issued.

DIAGNOSTICS
     On success, a zero is returned indicating that a rate guarantee has been
     granted and the stream indentifier of the rate guarantee is returned in
     the gr_stream_id field. In order to make use of this reservation, a
     grio_associate_file call has to be made at a future time when the
     application needs the reservation to be activated.  If the desired rate
     cannot be guaranteed a -1 is returned. In case of success, the system
     will make every effort to honour the guarantee if the file system has a
     realtime partition and is part of an XLV.  The errno variable is set to
     indicate the error.  The following error codes are defined:

     [EIO]     The calling process could not communicate with the ggd daemon.

     [EBADF]   The specified file system does not exist.

     [EIO]     The specified start time is invalid, or there is an invalid set
               of flags specified in the gr_flags field.

     [ENOSPC]  The requested bandwidth could not be guaranteed. Upon return
               the gr_opsize and gr_optime fields describe the maximum
               bandwidth left for reservation. The gr_errordev field contains
               the name of the device where the bandwidth was not available.

     [EPERM]   The process does not have root permissions or CAP_DEVICE_MGMT
               priviledge.

     [EINVAL]  The input griorp is invalid.

     [EACCESS] All the disks in the xlv comprising the file system do not have
               the same iosize, or the iosize of one or more disks was
               invalid.


FILES
     /etc/grio_disks

NOTE
     The guaranteed rate I/O capabilities described in this man page refer to
     the version one GRIO implementation. Refer to grio2(5) for information
     covering the newer GRIO Version 2 implementation which supports both
     local and clustered XVM volumes.

SEE ALSO
     ggd(1M), grio_associate_file(3X), grio_query_fs(3X),
     grio_action_list(3X), grio_reserve_file(3X), grio_unreserve_bw(3X),
     grio_disk(4), grio(5)


                                                                        Page 3