Developer Guide and Reference

ID 767251
Date 10/31/2024
Public
Document Table of Contents

PXFFCNTL

POSIX Subroutine: Manipulates an open file descriptor. This routine is only available for Linux.

Module

USE IFPOSIX

CALL PXFFCNTL (ifildes,icmd,iargin,iargout,ierror)

ifildes

(Input) INTEGER(4). A file descriptor.

icmd

(Input) INTEGER(4). Defines an action for the file descriptor.

iargin

(Input; output) INTEGER(4). Interpretation of this argument depends on the value of icmd.

iargout

(Output) INTEGER(4). Interpretation of this argument depends on the value of icmd.

ierror

(Output) INTEGER(4). The error status.

If successful, ierror is set to zero; otherwise, an error code.

PXFFCNTL is a multi-purpose subroutine that causes an action to be performed on a file descriptor. The action, defined in icmd, can be obtained by using the values of predefined macros in C header fcntl.h, or by using PXFCONST or IPXFCONST with one of the following constant names:

Constant

Action

F_DUPFD

Returns into iargout the lowest available unopened file descriptor greater than or equal to iargin. The new file descriptor refers to the same open file as ifildes and shares any locks. The system flag FD_CLOEXEC for the new file descriptor is cleared so the new descriptor will not be closed on a call to PXFEXEC subroutine.

F_GETFD

Returns into iargout the value of system flag FD_CLOEXEC associated with ifildes. In this case, iargin is ignored.

F_SETFD

Sets or clears the system flag FD_CLOEXEC for file descriptor ifildes. The PXFEXEC family of functions will close all file descriptors with the FD_CLOEXEC flag set. The value for FD_CLOEXEC is obtained from argument iargin.

F_GETFL

Returns the file status flags for file descriptor ifildes. Unlike F_GETFD, these flags are associated with the file and shared by all descriptors. A combination of the following flags, which are symbolic names for PXFCONST or IPXFCONST, can be returned:

  • O_APPEND - Specifies the file is opened in append mode.

  • O_NONBLOCK - Specifies when the file is opened, it does not block waiting for data to become available.

  • O_RDONLY - Specifies the file is opened for reading only.

  • O_RDWR - Specifies the file is opened for both reading and writing.

  • O_WRONLY - Specifies the file is opened for writing only.

F_SETFL

Sets the file status flags from iargin for file descriptor ifildes. Only O_APPEND or O_NONBLOCK flags can be modified. In this case, iargout is ignored.

F_GETLK

Gets information about a lock. Argument iargin must be a handle of structure flock. This structure is taken as the description of a lock for the file. If there is a lock already in place that would prevent this lock from being locked, it is returned to the structure associated with handle iargin. If there are no locks in place that would prevent the lock from being locked, field l_type in the structure is set to the value of the constant with symbolic name F_UNLCK.

F_SETLK

Sets or clears a lock. Argument iargin must be a handle of structure flock. The lock is set or cleared according to the value of structure field l_type. If the lock is busy, an error is returned.

F_SETLKW

Sets or clears a lock, but causes the process to wait if the lock is busy. Argument iargin must be a handle of structure flock. The lock is set or cleared according to the value of structure field l_type. If the lock is busy, PXFCNTL waits for an unlock.

NOTE:

To get a handle for an instance of the flock structure, use PXFSTRUCTCREATE with the string 'flock' for the structure name.