grio_reserve_file(3X) grio_reserve_file(3X) NAME grio_reserve_file - request a guaranteed rate I/O reservation on a file SYNOPSIS #include <grio.h> int grio_reserve_file( int fd, grio_resv_t *griorp); DESCRIPTION grio_reserve_file tries to obtain the I/O-rate guarantee specified by the griop structure on the file associated with fd. The contents of the structure pointed to by griop 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 is a realtime file on an XFS filesystem. 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 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 priviledge. [EINVAL] The input fd or 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_fs(3X), grio_unreserve_bw(3X), grio_disk(4), grio(5) Page 3