| Previous | Contents | Index |
Performs controlling operations on an open file.
#include <sys/types.h>#include <unistd.h>
#include <fcntl.h>
int fcntl (int file_desc, int request [, int arg]);
int fcntl (int file_desc, int request [, struct flock *arg]);
file_desc
An open file descriptor obtained from a successful open , fcntl , or pipe function.request
The operation to be performed.arg
A variable that depends on the value of the request argument.For a request of F_DUPFD, F_SETFD, or F_SETFL, specify arg as an int .
For a request of F_GETFD and F_GETFL, do not specify arg.
For a request of F_GETLK, F_SETLK, or F_SETLKW specify arg as a pointer to a flock structure.
The fcntl function performs controlling operations on the open file specified by the file_desc argument.The values for the request argument are defined in the header file <fcntl.h> , and include the following:
F_DUPFD Returns a new file descriptor that 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 file as the original file descriptor ( file_desc). The FD_CLOEXEC flag associated with the new file descriptor is cleared to keep the file open across calls to one of the exec functions.
The following two calls are equivalent:
fid = dup(file_desc);
fid = fcntl(file_desc, F_DUPFD, 0);
Consider the following call:
fid = dup2(file_desc, arg);
It is similar (but not equivalent) to:
close(arg);
fid = fcntl(file_desc, F_DUPFD, arg);
F_GETFD Gets the value of the close-on-exec flag associated with the file descriptor file_desc. File descriptor flags are associated with a single file descriptor and do not affect other file descriptors that refer to the same file. The arg argument should not be specified. F_SETFD Sets the close-on-exec flag associated with file_desc to the value of the third argument, taken as type int . If the third argument is 0, the file remains open across the exec functions, which means that a child process spawned by the exec function inherits this file descriptor from the parent.
If the third argument is FD_CLOEXEC , the file is closed on successful execution of the next exec function, which means that the child process spawned by the exec function will not inherit this file descriptor from the parent.
F_GETFL Gets the file status flags and file access modes, defined in <fcntl.h> , for the file description associated with file_desc. The file access modes can be extracted from the return value using the mask O_ACCMODE, which is defined in <fcntl.h> . File status flags and file access modes are associated with the file description and do not affect other file descriptors that refer to the same file with different open file descriptions. F_SETFL Sets the file status flags, defined in <fcntl.h> , for the file description associated with file_desc from the corresponding bits in the third argument, arg, taken as type int . Bits corresponding to the file access mode and the file creation flags, as defined in <fcntl.h> , 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 unspecified. Note: The only status bit recognized is O_APPEND. Support for O_APPEND is not standard-compliant. The X/Open standard states that "File status flags and file access modes are associated with the file description and do not affect other file descriptors that refer to the same file with different open file descriptions." However, because the append bit is stored in the FCB, all file descriptors using the same FCB are using the same append flag, so that setting this flag with fcntl(F_SETFL) will affect all files sharing the FCB; that is, all files duplicated from the same file descriptor.
Record Locking Requests F_GETLK Gets the first lock that blocks the lock description pointed to by the arg parameter, taken as a pointer to type struct flock . The information retrieved overwrites the information passed to the fcntl function in the flock structure. If no lock is found that would prevent this lock from being created, then the structure is left unchanged except for the lock type, which is set to F_UNLCK. F_SETLK Sets or clears a file segment lock according to the lock description pointed to by arg, taken as a pointer to type struct flock . F_SETLK is used to establish shared locks (F_RDLCK), or exclusive locks (F_WRLCK), as well as remove either type of lock (F_UNLCK). If a shared (read) or exclusive (write) lock cannot be set, the fcntl function returns immediately with a value of - 1. An unlock (F_UNLCK) request in which the l_len of the flock structure is nonzero and the offset of the last byte of the requested segment is the maximum value for an object of type off_t , when the process has an existing lock in which l_len is 0 and which includes the last byte of the requested segment, is treated as a request to unlock from the start of the requested segment with an l_len equal to 0. Otherwise, an unlock (F_UNLCK) request attempts to unlock only the requested file.
F_SETLKW Same as F_SETLK except that if a shared or exclusive lock is blocked by other locks, the process will wait until it is unblocked. If a signal is received while fcntl is waiting for a region, the function is interrupted, - 1 is returned, and errno is set to EINTR. File Locking
The C RTL supports byte-range file locking using the F_GETLK, F_SETLK, and F_SETLKW commands of the fcntl function, as defined in the X/Open specification. Byte-range file locking is supported across OpenVMS clusters. You can only use offsets that fit into 32-bit unsigned integers.
When a shared lock is set on a segment of a file, other processes on the cluster are able to set shared locks on that segment or a portion of it. A shared lock prevents any other process from setting an exclusive lock on any portion of the protected area. A request for a shared lock fails if the file descriptor was not opened with read access.
An exclusive lock prevents any other process on the cluster from setting a shared lock or an exclusive lock on any portion of the protected area. A request for an exclusive lock fails if the file descriptor was not opened with write access.
The flock structure describes the type (l_type), starting offset (l_whence), relative offset (l_start), size (l_len) and process ID (l_pid) of the segment of the file to be affected.
The value of l_whence is set to SEEK_SET, SEEK_CUR or SEEK_END, to indicate that the relative offset l_start bytes is measured from the start of the file, from the current position, or from the end of the file, respectively. The value of l_len is the number of consecutive bytes to be locked. The l_len value may be negative (where the definition of off_t permits negative values of l_len). The l_pid field is only used with F_GETLK to return the process ID of the process holding a blocking lock. After a successful F_GETLK request, the value of l_whence becomes SEEK_SET.
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 may not be negative relative to the beginning of the file. If l_len is set to 0 (zero), a lock may be set to always extend to the largest possible value of the file offset for that file. If such a lock also has l_start set to 0 (zero) and l_whence is set to SEEK_SET, the whole file is locked.
Changing or unlocking a portion from the middle of a larger locked segment leaves a smaller segment at either end. Locking a segment that is already locked by the calling process causes the old lock type to be removed and the new lock type to take effect.
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.
If the request argument is F_SETLKW, the lock is blocked by some lock from another process, and putting the calling process to sleep to wait for that lock to become free would cause a deadlock, then the application will hang.
n Upon successful completion, the value returned depends on the value of the request argument as follows:
- F_DUPFD -- Returns a new file descriptor.
- F_GETFD -- Returns FD_CLOEXEC or 0.
- F_SETFD , F_GETLK , F_SETLK , F_UNLCK -- Return a value other than - 1.
- 1 Indicates that an error occurred. The function sets errno to one of the following values:
- EACCES -- The request argument is F_SETLK; 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 (F_WRLCK) lock and the some portion of the segment of a file to be locked is already shared-locked or exclusive-locked by another process.
- EBADF -- The file_desc argument is not a valid open file descriptor and the arg argument is negative or greater than or equal to the per-process limit.
The request parameter is F_SETLK or F_SETLKW, the type of lock ( l_type) is a shared lock (F_RDLCK), and file_desc is not a valid file descriptor open for reading.
The type of lock ( l_type) is an exclusive lock (F_WRLCK), and file_desc is not a valid file descriptor open for writing.
- EFAULT -- The arg argument is an invalid address.
- EINVAL -- The request argument is F_DUPFD and arg is negative or greater than or equal to OPEN_MAX.
Either the OPEN_MAX value or the per-process soft descriptor limit is checked.
An illegal value was provided for the request argument.
The request argument is F_GETLK, F_SETLK, or F_SETLKW and the data pointed to by arg is invalid, or file_desc refers to a file that does not support locking.
- EMFILE -- The request argument is F_DUPFD and too many or OPEN_MAX file descriptors are currently open in the calling process, or no file descriptors greater than or equal to arg are available.
Either the OPEN_MAX value or the per-process soft descriptor limit is checked.
- EOVERFLOW -- One of the values to be returned cannot be represented correctly.
The request argument is F_GETLK, F_SETLK, or F_SETLKW and the smallest or, if l_len is nonzero, the largest offset of any byte in the requested segment cannot be represented correctly in an object of type off_t .
- EINTR -- The request argument is F_SETLKW, and the function was interrupted by a signal.
- ENOLCK -- The request argument is F_SETLK or F_SETLKW, and satisfying the lock or unlock request would exceed the configurable system limit of NLOCK_RECORD.
- ENOMEM -- The system was unable to allocate memory for the requested file descriptor.
Converts its argument to a null-terminated string of ASCII digits and returns the address of the string. The string is stored in a thread-specific location created by the HP C RTL.
#include <stdlib.h>char *fcvt (double value, int ndigits, int *decpt, int *sign);
value
An object of type double that is converted to a null-terminated string of ASCII digits.ndigits
The number of ASCII digits after the decimal point to be used in the converted string.decpt
The position of the decimal point relative to the first character in the returned string. The returned string does not contain the actual decimal point. A negative int value means that the decimal point is decpt number of spaces to the left of the returned digits (the spaces are filled with zeros). A 0 value means that the decimal point is immediately to the left of the first digit in the returned string.sign
An integer value that indicates whether the value argument is positive or negative. If value is negative, the fcvt function places a nonzero value at the address specified by sign. Otherwise, the functions assign 0 to the address specified by sign.
The fcvt function converts value to a null-terminated string and returns a pointer to it. The resulting low-order digit is rounded to the correct digit for outputting ndigits digits in C F-format. The decpt argument is assigned the position of the decimal point relative to the first character in the string.In C F-format, ndigits is the number of digits desired after the decimal point. Very large numbers produce a very long string of digits before the decimal point, and ndigit of digits after the decimal point. For large numbers, it is preferable to use the gcvt or ecvt function so that E-format is used.
Repeated calls to the fcvt function overwrite any existing string.
The ecvt , fcvt , and gcvt functions represent the following special values specified in the IEEE Standard for floating-point arithmetic:
Value Representation Quiet NaN NaNQ Signalling NaN NaNS +Infinity Infinity - Infinity - Infinity The sign associated with each of these values is stored into the sign argument. In IEEE floating-point representation, a value of 0 (zero) can be positive or negative, as set by the sign argument.
See also gcvt and ecvt .
x A pointer to the converted string.
Determines the positive difference between its arguments.
#include <math.h>double fdim (double x, double y);
float fdimf (float x, float y);
long double fdiml (long double x, long double y);
x
A real value.y
A real value.
The fdim functions determine the positive difference between their arguments. If x is greater than y, x - y is returned. If x is less than or equal to y, +0 is returned.
n Upon success, the positive difference value. HUGE_VAL If x - y is positive and overflows; errno is set to ERANGE. 0 If x - y is positive and underflows; errno is set to ERANGE. NaN x or y is NaN; errno is set to EDOM.
Associates a file pointer with a file descriptor returned by an open , creat , dup , dup2 , or pipe function.
#include <stdio.h>FILE *fdopen (int file_desc, char *a_mode);
file_desc
The file descriptor returned by open , creat , dup , dup2 , or pipe .a_mode
The access mode indicator. See the fopen function for a description. Note that the access mode specified must agree with the mode used to originally open the file. This includes binary/text access mode ("b" mode on fdopen and the "ctx=bin" option on creat or open ).
The fdopen function allows you to access a file, originally opened by one of the UNIX I/O functions, with Standard I/O functions. Ordinarily, a file can be accessed by either a file descriptor or by a file pointer, but not both, depending on the way you open it. For more information, see Chapters 1 and 2.
pointer Indicates that the operation has succeeded. NULL Indicates that an error has occurred.
Tests a file to see if the end-of-file has been reached.
#include <stdio.h>int feof (FILE *file_ptr);
file_ptr
A file pointer.
nonzero integer Indicates that the end-of-file has been reached. 0 Indicates that the end-of-file has not been reached.
Same as feof , except used only within a scope protected by flockfile and funlockfile .
#include <stdio.h>int feof_unlocked (FILE *file_ptr);
file_ptr
A file pointer.
The reentrant version of the feof function is locked against multiple threads calling it simultaneously. This incurs overhead to ensure integrity of the stream. The unlocked version of this call, feof_unlocked can be used to avoid the overhead. The feof_unlocked function is functionally identical to the feof function, except that it is not required to be implemented in a thread-safe manner. The feof_unlocked function can be safely used only within a scope that is protected by the flockfile and funlockfile functions used as a pair. The caller must ensure that the stream is locked before feof_unlocked is used.See also flockfile , ftrylockfile , and funlockfile .
nonzero integer Indicates end-of-file has been reached. 0 Indicates end-of-file has not been reached.
| Previous | Next | Contents | Index |