prio(3X)

NAME
     prio: prioSetBandwidth, prioGetBandwidth, prioLock, prioUnlock - Priority
     IO operations.

SYNOPSIS
     #include <sys/prio.h>

     int prioSetBandwidth (int fd, enum prioAllocateType_e mode,
          bandwidth_t bytesec, pid_t *lock_holder);

     int prioGetBandwidth(inf fd, bandwidth_t *read_bytesec,
          bandwidth_t *write_bytesec);

     int prioLock (pid_t *lock_holder);

     int prioUnlock();

DESCRIPTION
     prioSetBandwidth tries to allocate bandwidth:  bytesec in bytes per
     second on a file descriptor fd.  mode specifies the allocation direction,
     which can be one of PRIO_READ_ALLOCATE, PRIO_WRITE_ALLOCATE,
     PRIO_READWRITE_ALLOCATE. The allocation mode must match the file opening
     mode. If a read direction allocation is requested, the file must have
     been opened for read; if a write direction allocation is requested, the
     file must have been opened for write. Otherwise, prioSetBandwidth will
     fail.

     If another process holds the global lock for bandwidth allocation,
     prioSetBandwidth will fail and lock_holder will have the process id of
     the process which is holding the lock.

     On success, the actually allocated bandwidth would be more than or equal
     to the requested bandwidth because the underlying hardware manages
     bandwidth allocation on cache line size transfers. Partial line transfers
     requires the system to adjust upwards to meet the request.

     prioGetBandwidth obtains bandwidth allocation on file descriptor fd.
     read_bytesec and write_bytesec have bandwidth in bytes per second in read
     and write direction, respectively.

     Some applications may want to do a set of allocation/reallocation of
     bandwidth without other applications' interference. A system global lock
     is provided to support this multi-step reallocation.  The application
     acquires the lock through prioLock. The application that holds the lock
     can raise or lower current allocations as well as request new allocations
     without dealing with concurrent bandwidth allocations from another
     application. At the end of the allocation sequence, the lock must be
     released with the prioUnlock call. When an application is holding the
     lock, prioSetBandwidth in other applications will fail.
     When prioLock fails because another application is holding the lock,
     lock_holder has the process ID of the application.

     When a process that holds the lock dies for some reason before it calls
     prioUnlock , the system will release the lock.

NOTE
     It is not required for an application to call prioLock before it requests
     bandwidth allocation.

     The application should be compiled with -lprio option.

     In IRIX 6.5, the Priority I/O APIs have been merged with the GRIO APIs.
     As a result, the use of the Priority I/O APIs is deprecated. For
     backwards compatibility, prioSetBandwidth and prioGetBandwidth are still
     supported.  prioLock and prioUnlock are merely stubs. No locking or
     atomicity is guaranteed. Please refer to grio(5) for further details.

DIAGNOSTICS
     On successful completion of all these functions, a zero is returned
     indicating that the request has been granted. If the request cannot be
     granted, a -1 is returned and errno is set to the appropriate value.

     [ENOPKG]  Bandwidth allocation is not supported on this system.

     [E2BIG]   Bandwidth allocation failed because not enough bandwidth is
               available.

     [EBADFD]  File descriptor is invalid.

     [EINVAL]  One or more parameters are invalid.

     [ENOLCK]  Another application is holding the lock.

SEE ALSO
     prio(5), prioinfo(1), grio(5)