Windows PowerShell command on Get-command fcntl

Manual Pages for UNIX Operating System command usage for man fcntl

System Calls fcntl(2)

NAME

fcntl - file control

SYNOPSIS

#include

int fcntl(int fildes, int cmd, /* arg */ ...);

DESCRIPTION

The fcntl() function provides for control over open files.

The fildes argument is an open file descriptor.

The fcntl() function can take a third argument, arg, whose

data type, value, and use depend upon the value of cmd. The cmd argument specifies the operation to be performed by

fcntl().

The values for cmd are defined in and include:

F_DUPFD Return a new file descriptor which is the

lowest numbered available (that is, not already open) file descriptor greater than or equal to the third argument, arg, taken as an integer of type int. The new file descriptor refers to the same open file description as the original file descriptor, and shares any

locks. The FD_CLOEXEC flag associated with

the new file descriptor is cleared to keep the file open across calls to one of the exec(2) functions.

F_DUP2FD Similar to F_DUPFD, but always returns arg.

F_DUP2FD closes arg if it is open and not

equal to fildes. F_DUP2FD is equivalent to

dup2(fildes, arg).

F_FREESP Free storage space associated with a section

of the ordinary file fildes. The section is specified by a variable of data type struct flock pointed to by arg. The data type struct

flock is defined in the header (see

fcntl.h(3HEAD)) and is described below. Note

that all file systems might not support all

possible variations of F_FREESP arguments. In

particular, many file systems allow space to

SunOS 5.11 Last change: 17 Jan 2007 1

System Calls fcntl(2)

be freed only at the end of a file.

F_FREESP64 Equivalent to F_FREESP, but takes a struct

flock64 argument rather than a struct flock argument.

F_ALLOCSP Allocate space for a section of the ordinary

file fildes. The section is specified by a variable of data type struct flock pointed to by arg. The data type struct flock is defined

in the header (see fcntl.h(3HEAD)

and is described below.

F_ALLOCSP64 Equivalent to F_ALLOCSP, but takes a struct

flock64 argument rather than a struct flock argument.

F_GETFD Get the file descriptor flags defined in

that are associated with the file

descriptor fildes. File descriptor flags are associated with a single file descriptor and do not affect other file descriptors that refer to the same file.

F_GETFL Get the file status flags and file access

modes, defined in , for the file

descriptor specified by fildes. The file access modes can be extracted from the return

value using the mask O_ACCMODE, which is

defined in . File status flags and

file access modes do not affect other file descriptors that refer to the same file with different open file descriptions.

F_GETOWN If fildes refers to a socket, get the process

or process group ID specified to receive

SIGURG signals when out-of-band data is

available. Positive values indicate a process

ID; negative values, other than -1, indicate

a process group ID. If fildes does not refer to a socket, the results are unspecified.

F_GETXFL Get the file status flags, file access modes,

and file creation and assignment flags,

defined in , for the file descriptor

SunOS 5.11 Last change: 17 Jan 2007 2

System Calls fcntl(2)

specified by fildes. The file access modes can be extracted from the return value using

the mask O_ACCMODE, which is defined in

. File status flags, file access

modes, and file creation and assignment flags do not affect other file descriptors that refer to the same file with different open file descriptions.

F_SETFD Set the file descriptor flags defined in

, that are associated with fildes,

to the third argument, arg, taken as type

int. If the FD_CLOEXEC flag in the third

argument is 0, the file will remain open across the exec() functions; otherwise the file will be closed upon successful execution of one of the exec() functions.

F_SETFL Set the file status flags, defined in

, for the file descriptor specified

by fildes from the corresponding bits in the arg argument, taken as type int. Bits corresponding to the file access mode and file creation and assignment flags that are set in arg are ignored. If any bits in arg other than those mentioned here are changed

by the application, the result is unspeci-

fied.

F_SETOWN If fildes refers to a socket, set the process

or process group ID specified to receive

SIGURG signals when out-of-band data is

available, using the value of the third argu-

ment, arg, taken as type int. Positive values indicate a process ID; negative values, other

than -1, indicate a process group ID. If

fildes does not refer to a socket, the results are unspecified. The following commands are available for advisory record locking. Record locking is supported for regular files, and may be supported for other files.

F_GETLK Get the first lock which blocks the lock

description pointed to by the third argument, arg, taken as a pointer to type struct flock,

defined in . The information

SunOS 5.11 Last change: 17 Jan 2007 3

System Calls fcntl(2)

retrieved overwrites the information passed to

fcntl() in the structure flock. If no lock is

found that would prevent this lock from being created, then the structure will be left unchanged except for the lock type which will

be set to F_UNLCK.

F_GETLK64 Equivalent to F_GETLK, but takes a struct

flock64 argument rather than a struct flock argument.

F_SETLK Set or clear a file segment lock according to

the lock description pointed to by the third argument, arg, taken as a pointer to type

struct flock, defined in . F_SETLK is

used to establish shared (or read) locks

(F_RDLCK) or exclusive (or write) locks

(F_WRLCK), as well as to remove either type of

lock (F_UNLCK). F_RDLCK, F_WRLCK and F_UNLCK

are defined in . If a shared or

exclusive lock cannot be set, fcntl() will

return immediately with a return value of -1.

F_SETLK64 Equivalent to F_SETLK, but takes a struct

flock64 argument rather than a struct flock argument.

F_SETLKW This command is the same as F_SETLK except

that if a shared or exclusive lock is blocked by other locks, the process will wait until the request can be satisfied. If a signal that

is to be caught is received while fcntl() is

waiting for a region, fcntl() will be inter-

rupted. Upon return from the process' signal

handler, fcntl() will return -1 with errno set

to EINTR, and the lock operation will not be done.

F_SETLKW64 Equivalent to F_SETLKW, but takes a struct

flock64 argument rather than a struct flock argument. When a shared lock is set on a segment of a file, other processes will be able to set shared locks on that segment or a portion of it. A shared lock prevents any other process

SunOS 5.11 Last change: 17 Jan 2007 4

System Calls fcntl(2)

from setting an exclusive lock on any portion of the pro-

tected area. A request for a shared lock will fail if the file descriptor was not opened with read access.

An exclusive lock will prevent any other process from set-

ting a shared lock or an exclusive lock on any portion of the protected area. A request for an exclusive lock will fail if the file descriptor was not opened with write access.

The flock structure contains at least the following ele-

ments:

short l_type; /* lock operation type */

short l_whence; /* lock base indicator */

off_t l_start; /* starting offset from base */

off_t l_len; /* lock length; l_len == 0 means

until end of file */

int l_sysid; /* system ID running process holding lock */

pid_t l_pid; /* process ID of process holding lock */

The value of l_whence is SEEK_SET, SEEK_CUR, or SEEK_END, to

indicate that the relative offset l_start bytes will be

measured from the start of the file, current position or end

of the file, respectively. The value of l_len is the number

of consecutive bytes to be locked. The value of l_len may be

negative (where the definition of off_t permits negative

values of l_len). After a successful F_GETLK or F_GETLK64

request, that is, one in which a lock was found, the value

of l_whence will be SEEK_SET.

The l_pid and l_sysid fields are used only with F_GETLK or

F_GETLK64 to return the process ID of the process holding a

blocking lock and to indicate which system is running that process.

If l_len is positive, the area affected starts at l_start

and ends at l_start + l_len - 1. If l_len is negative, the

area affected starts at l_start + l_len and ends at l_start

- 1. Locks may start and extend beyond the current end of a

file, but must not be negative relative to the beginning of

the file. A lock will be set to extend to the largest possi-

ble value of the file offset for that file by setting l_len

to 0. If such a lock also has l_start set to 0 and l_whence

is set to SEEK_SET, the whole file will be locked.

SunOS 5.11 Last change: 17 Jan 2007 5

System Calls fcntl(2)

If a process has an existing lock in which l_len is 0 and

which includes the last byte of the requested segment, and

an unlock (F_UNLCK) request is made in which l_len is non-

zero and the offset of the last byte of the requested seg-

ment is the maximum value for an object of type off_t, then

the F_UNLCK request will be treated as a request to unlock

from the start of the requested segment with an l_len equal

to 0. Otherwise, the request will attempt to unlock only the requested segment. There will be at most one type of lock set for each byte in

the file. Before a successful return from an F_SETLK,

F_SETLK64, F_SETLKW, or F_SETLKW64 request when the calling

process has previously existing locks on bytes in the region specified by the request, the previous lock type for each byte in the specified region will be replaced by the new lock type. As specified above under the descriptions of

shared locks and exclusive locks, an F_SETLK, F_SETLK64,

F_SETLKW, or F_SETLKW64 request will (respectively) fail or

block when another process has existing locks on bytes in

the specified region and the type of any of those locks con-

flicts with the type specified in the request. All locks associated with a file for a given process are removed when a file descriptor for that file is closed by that process or the process holding that file descriptor terminates. Locks are not inherited by a child process created using fork(2). A potential for deadlock occurs if a process controlling a locked region is put to sleep by attempting to lock another process' locked region. If the system detects that sleeping until a locked region is unlocked would cause a deadlock,

fcntl() will fail with an EDEADLK error.

The following values for cmd are used for file share reser-

vations. A share reservation is placed on an entire file to allow cooperating processes to control access to the file.

F_SHARE Sets a share reservation on a file with the

specified access mode and designates which types of access to deny.

F_UNSHARE Remove an existing share reservation.

SunOS 5.11 Last change: 17 Jan 2007 6

System Calls fcntl(2)

File share reservations are an advisory form of access con-

trol among cooperating processes, on both local and remote

machines. They are most often used by DOS or Windows emula-

tors and DOS based NFS clients. However, native UNIX ver-

sions of DOS or Windows applications may also choose to use this form of access control. A share reservation is described by an fshare structure

defined in , which is included in as

follows: typedef struct fshare {

short f_access;

short f_deny;

int f_id;

} fshare_t;

A share reservation specifies the type of access, f_access,

to be requested on the open file descriptor. If access is granted, it further specifies what type of access to deny

other processes, f_deny. A single process on the same file

may hold multiple non-conflicting reservations by specify-

ing an identifier, f_id, unique to the process, with each

request.

An F_UNSHARE request releases the reservation with the

specified f_id. The f_access and f_deny fields are ignored.

Valid f_access values are:

F_RDACC Set a file share reservation for read-only

access.

F_WRACC Set a file share reservation for write-only

access.

F_RWACC Set a file share reservation for read and write

access.

Valid f_deny values are:

F_COMPAT Set a file share reservation to compatibility

mode.

SunOS 5.11 Last change: 17 Jan 2007 7

System Calls fcntl(2)

F_RDDNY Set a file share reservation to deny read access

to other processes.

F_WRDNY Set a file share reservation to deny write

access to other processes.

F_RWDNY Set a file share reservation to deny read and

write access to other processes.

F_NODNY Do not deny read or write access to any other

process.

RETURN VALUES

Upon successful completion, the value returned depends on cmd as follows:

F_DUPFD A new file descriptor.

F_FREESP Value of 0.

F_GETFD Value of flags defined in . The

return value will not be negative.

F_GETFL Value of file status flags and access modes.

The return value will not be negative.

F_GETLK Value other than -1.

F_GETLK64 Value other than -1.

F_GETOWN Value of the socket owner process or process

group; this will not be -1.

F_GETXFL Value of file status flags, access modes, and

creation and assignment flags. The return value will not be negative.

F_SETFD Value other than -1.

SunOS 5.11 Last change: 17 Jan 2007 8

System Calls fcntl(2)

F_SETFL Value other than -1.

F_SETLK Value other than -1.

F_SETLK64 Value other than -1.

F_SETLKW Value other than -1.

F_SETLKW64 Value other than -1.

F_SETOWN Value other than -1.

F_SHARE Value other than -1.

F_UNSHARE Value other than -1.

Otherwise, -1 is returned and errno is set to indicate the

error.

ERRORS

The fcntl() function will fail if:

EAGAIN The cmd argument is F_SETLK or F_SETLK64, the

type of lock (l_type) is a shared (F_RDLCK) or

exclusive (F_WRLCK) lock, and the segment of a

file to be locked is already exclusive-locked

by another process; or the type is an exclusive lock and some portion of the segment of a file

to be locked is already shared-locked or

exclusive-locked by another process.

The cmd argument is F_FREESP, the file exists,

mandatory file/record locking is set, and there are outstanding record locks on the file; or

the cmd argument is F_SETLK, F_SETLK64,

F_SETLKW, or F_SETLKW64, mandatory file/record

locking is set, and the file is currently being mapped to virtual memory using mmap(2).

The cmd argument is F_SHARE and f_access con-

flicts with an existing f_deny share reserva-

tion.

SunOS 5.11 Last change: 17 Jan 2007 9

System Calls fcntl(2)

EBADF The fildes argument is not a valid open file

descriptor; or the cmd argument is F_SETLK,

F_SETLK64, F_SETLKW, or F_SETLKW64, the type of

lock, l_type, is a shared lock (F_RDLCK), and

fildes is not a valid file descriptor open for

reading; or the type of lock l_type is an

exclusive lock (F_WRLCK) and fildes is not a

valid file descriptor open for writing.

The cmd argument is F_FREESP and fildes is not

a valid file descriptor open for writing.

The cmd argument is F_DUP2FD, and arg is nega-

tive or is not less than the current resource

limit for RLIMIT_NOFILE.

The cmd argument is F_SHARE, the f_access share

reservation is for write access, and fildes is not a valid file descriptor open for writing.

The cmd argument is F_SHARE, the f_access share

reservation is for read access, and fildes is not a valid file descriptor open for reading.

EFAULT The cmd argument is F_GETLK, F_GETLK64,

F_SETLK, F_SETLK64, F_SETLKW, F_SETLKW64, or

F_FREESP and the arg argument points to an

illegal address.

The cmd argument is F_SHARE or F_UNSHARE and

arg points to an illegal address.

EINTR The cmd argument is F_SETLKW or F_SETLKW64 and

the function was interrupted by a signal. EINVAL The cmd argument is invalid or not supported by

the file system; or the cmd argument is F_DUPFD

and arg is negative or greater than or equal to

OPEN_MAX; or the cmd argument is F_GETLK,

F_GETLK64, F_SETLK, F_SETLK64, F_SETLKW, or

F_SETLKW64 and the data pointed to by arg is

not valid; or fildes refers to a file that does not support locking.

The cmd argument is F_UNSHARE and a reservation

with this f_id for this process does not exist.

SunOS 5.11 Last change: 17 Jan 2007 10

System Calls fcntl(2)

EIO An I/O error occurred while reading from or writing to the file system.

EMFILE The cmd argument is F_DUPFD and either OPEN_MAX

file descriptors are currently open in the cal-

ling process, or no file descriptors greater than or equal to arg are available.

ENOLCK The cmd argument is F_SETLK, F_SETLK64,

F_SETLKW, or F_SETLKW64 and satisfying the lock

or unlock request would result in the number of locked regions in the system exceeding a

system-imposed limit.

ENOLINK Either the fildes argument is on a remote machine and the link to that machine is no

longer active; or the cmd argument is F_FREESP,

the file is on a remote machine, and the link to that machine is no longer active. EOVERFLOW One of the values to be returned cannot be represented correctly.

The cmd argument is F_GETLK, F_SETLK, or

F_SETLKW and the smallest or, if l_len is non-

zero, the largest, offset of any byte in the requested segment cannot be represented

correctly in an object of type off_t.

The cmd argument is F_GETLK64, F_SETLK64, or

F_SETLKW64 and the smallest or, if l_len is

non-zero, the largest, offset of any byte in

the requested segment cannot be represented

correctly in an object of type off64_t.

The fcntl() function may fail if:

EAGAIN The cmd argument is F_SETLK, F_SETLK64, F_SETLKW,

or F_SETLKW64, and the file is currently being

mapped to virtual memory using mmap(2).

EDEADLK The cmd argument is F_SETLKW or F_SETLKW64, the

lock is blocked by some lock from another process and putting the calling process to sleep, waiting for that lock to become free would cause a

SunOS 5.11 Last change: 17 Jan 2007 11

System Calls fcntl(2)

deadlock.

The cmd argument is F_FREESP, mandatory record

locking is enabled, O_NDELAY and O_NONBLOCK are

clear and a deadlock condition was detected.

ATTRIBUTES

See attributes(5) for descriptions of the following attri-

butes:

____________________________________________________________

| ATTRIBUTE TYPE | ATTRIBUTE VALUE |

|_____________________________|_____________________________|

| Interface Stability | Committed |

|_____________________________|_____________________________|

| MT-Level | Async-Signal Safe |

|_____________________________|_____________________________|

| Standard | See standards(5). |

|_____________________________|_____________________________|

write(2), dup2(3C), fcntl.h(3HEAD), attributes(5), stan-

dards(5) Programming Interfaces Guide NOTES In the past, the variable errno was set to EACCES rather than EAGAIN when a section of a file is already locked by another process. Therefore, portable application programs should expect and test for either value.

Advisory locks allow cooperating processes to perform con-

sistent operations on files, but do not guarantee exclusive access. Files can be accessed without advisory locks, but

inconsistencies may result. The network share locking proto-

col does not support the f_deny value of F_COMPAT. For net-

work file systems, if f_access is F_RDACC, f_deny is mapped

to F_RDDNY. Otherwise, it is mapped to F_RWDNY.

To prevent possible file corruption, the system may reject mmap() requests for advisory locked files, or it may reject advisory locking requests for mapped files. Applications

SunOS 5.11 Last change: 17 Jan 2007 12

System Calls fcntl(2)

that require a file be both locked and mapped should lock

the entire file (l_start and l_len both set to 0). If a file

is mapped, the system may reject an unlock request, result-

ing in a lock that does not cover the entire file. The process ID returned for locked files on network file systems might not be meaningful. If the file server crashes and has to be rebooted, the lock manager (see lockd(1M)) attempts to recover all locks that were associated with that server. If a lock cannot be reclaimed, the process that held the lock is issued a SIGLOST signal.

SunOS 5.11 Last change: 17 Jan 2007 13

Manual Pages for UNIX Operating System command usage for man fcntl

System Calls fcntl(2)

NAME

fcntl - file control

SYNOPSIS

#include

int fcntl(int fildes, int cmd, /* arg */ ...);

DESCRIPTION

The fcntl() function provides for control over open files.

The fcntl() function can take a third argument, arg, whose

fcntl().

The values for cmd are defined in and include:

flock is defined in the header (see

fcntl.h(3HEAD)) and is described below. Note

System Calls fcntl(2)

in the header (see fcntl.h(3HEAD)

that are associated with the file

modes, defined in , for the file

defined in . File status flags and

defined in , for the file descriptor

System Calls fcntl(2)

. File status flags, file access

, that are associated with fildes,

, for the file descriptor specified

defined in . The information

System Calls fcntl(2)

fcntl() in the structure flock. If no lock is

struct flock, defined in . F_SETLK is

are defined in . If a shared or

exclusive lock cannot be set, fcntl() will

is to be caught is received while fcntl() is

waiting for a region, fcntl() will be inter-

handler, fcntl() will return -1 with errno set

System Calls fcntl(2)

System Calls fcntl(2)

fcntl() will fail with an EDEADLK error.

System Calls fcntl(2)

defined in , which is included in as

System Calls fcntl(2)

RETURN VALUES

F_GETFD Value of flags defined in . The

System Calls fcntl(2)

ERRORS

The fcntl() function will fail if:

System Calls fcntl(2)

System Calls fcntl(2)

The fcntl() function may fail if:

System Calls fcntl(2)

ATTRIBUTES

| ATTRIBUTE TYPE | ATTRIBUTE VALUE |

SEE ALSO

write(2), dup2(3C), fcntl.h(3HEAD), attributes(5), stan-

System Calls fcntl(2)