grio_action_list(3X)                                      grio_action_list(3X)


NAME
     grio_action_list - atomically execute a list of bandwidth
     reserve/unreserve actions

SYNOPSIS
     #include <sys/grio.h>
     int grio_action_list( int num, grio_resv_t *grior_list);

DESCRIPTION
     grio_action_list tries to atomically execute a list of bandwidth
     reserve/unreserve actions as specified in grior_list. num is the total
     number of actions in the list. The actions are considered to be atomic in
     the sense that all the actions in the list are executed together.  No
     other action can interfere with the actions in the list once the first
     action in the list has been initiated.

     The contents of the list of structures pointed to by grior_list includes
     the following members:

     gr_action
          The type of action. Currently supported types are:

          GRIO_RESV_ACTION    This is a reservation request.

          GRIO_UNRESV_ACTION  This is an unreserve action.

     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.

          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.

          PER_FILE_GUAR       This is a per file guarantee. The gr_fd field of
                              the gr_object_u union is interpreted.

          PER_FILE_SYS_GUAR   This is a file system guarantee. This is
                              meaningful only for the XFS file system.

     gr_fsid
          The dev_t for the file system being reserved. Applies only for file
          system reservations.

     gr_fid
          The file descriptor which is being reserved.


DIAGNOSTICS
     On success, a zero is returned which indicates that all the sub-commands
     completed without errors.

     On failure a -1 is returned. Failure could be because of various reasons:
     If errno is set to EINVAL, this indicates that one of the parameters
     passed in to grio_action_list is invalid.  If errno indicates no error,
     but grio_action_list returns -1, this means that execution of one of the
     sub-commands failed.  The gr_error field of the relevant grio_resv_t
     structures 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 does not exist or already has a rate
               guarantee from this process.

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

     [ENOENT]  The specified file does not contain any extents. It is empty.

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

     [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_remove_request(3X), grio_reserve_fs(3X), grio_unreserve_bw(3X),
     grio_disk(4), grio(5)


                                                                        Page 3