grio_reserve_file(3X)grio_reserve_file(3X)NAMEgrio_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);
DESCRIPTIONgrio_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.
Page 1
grio_reserve_file(3X)grio_reserve_file(3X)
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.
Page 2
grio_reserve_file(3X)grio_reserve_file(3X)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 ALSOggd(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
