/** @file ../include/sys/fcntl.h
@internalComponent
*/
/** @fn open(const char *file, int flags, ...)
@param file
@param flags
@param ...
@return If successful, open returns a non-negative integer, termed a file descriptor. It returns
-1 on failure and sets errno to indicate the error.
The file name specified by file is opened for reading and/or writing, as specified by the argument flags , and the file descriptor returned to the calling process. The flags argument may indicate that the file is to be created if it does
not exist (by specifying the O_CREAT flag). In this case open requires a third argument, mode_t mode , and the file is created with mode as described in chmod and modified by the process' umask
value (see umask )
The flags specified are formed by OR'ing the following values
@code
O_RDONLYopen for reading only
O_WRONLYopen for writing only
O_RDWRopen for reading and writing
O_NONBLOCKdo not block on open
O_APPENDappend on each write
O_CREATcreate file if it does not exist
O_TRUNCtruncate size to 0
O_EXCLerror if create and file exists
O_SHLOCKatomically obtain a shared lock
O_EXLOCKatomically obtain an exclusive lock
O_DIRECTeliminate or reduce cache effects
O_FSYNCsynchronous writes
O_NOFOLLOWdo not follow symlinks
Following options are currently not supported :
O_NONBLOCK, O_SHLOCK, O_EXLOCK, O_DIRECT, O_FSYNC, O_NOFOLLOW.
@endcode
O_LARGEFILE
This flag, if passed into the open() API, enables it to open a large file (files with 64 bit file sizes)
Opening a file with O_APPEND set causes each write on the file
to be appended to the end.
If O_TRUNC is specified, and the file exists, the file is truncated to
zero length.
If O_EXCL is set with O_CREAT and the file already
exists, open returns an error.
This may be used to
implement a simple exclusive access locking mechanism.
If O_EXCL is set and the last component of the pathname is
a symbolic link, open will fail even if the symbolic
link points to a non-existent name.
If the O_NONBLOCK flag is specified and the open system call would result in the process being blocked for some
reason (e.g., waiting for carrier on a dialup line), open returns immediately. The descriptor remains in non-blocking mode
for subsequent operations. This mode need not have any effect on files other
than FIFOs.
If O_FSYNC is used in the mask all writes will immediately be written
to disk, the kernel will not cache written data and all writes on the descriptor
will not return until the data to be written completes.
If O_NOFOLLOW is used in the mask and the target file passed to open is a symbolic link the open will fail.
When opening a file, a lock with flock semantics can be obtained by setting O_SHLOCK for a shared lock or O_EXLOCK for an exclusive lock. If creating a file with O_CREAT, the request for the lock will never fail (provided that the
underlying file system supports locking).
O_DIRECT may be used to minimize or eliminate the cache effects of
reading and writing. The system will attempt to avoid caching the data being
read or written. If it cannot avoid caching the data, it will minimize the impact
the data has on the cache. Use of this flag can drastically reduce performance
if not used with care.
If successful, open returns a non-negative integer termed a file descriptor. It returns
-1 on failure. The file pointer used to mark the current position within the
file is set to the beginning of the file.
When a new file is created it is given the group of the directory
which contains it.
The new descriptor is set to remain open across execve system calls.; See close and fcntl .
The system imposes a limit on the number of file descriptors
open simultaneously by one process.
The getdtablesize system call returns the current system limit.
Notes:
1) Mode values for group and others are ignored
2) Execute bit and setuid on exec bit are ignored.
3) The default working directory of a process is initalized to C: \\private\\UID
(UID of the calling application) and any data written into this directory persists
between phone resets.
4) If the specified file is a symbolic link and the file it is pointing to
is invalid, the symbolic link file will be automatically removed.
5) A file in cannot be created with write-only permissions. Attempting to create
a file with write-only permissions will result in a file with read-write permission.
6) Creating a new file with the O_CREAT flag does not alter the time stamp
of the parent directory.
7) A file has only two time stamps: access and modification. Creation time
stamp of the file is not supported and access time stamp is initially set equal
to modification time stamp.
8) Users should not use O_DIRECT flag as the underlying implementation makes explicit
use of O_DIRECT by default. Instead if the users want to use read/write
buffering they can use O_BUFFERED.
9) Users should not use O_BINARY flag as the underlying implementation opens a file
in binary mode by default. Instead if the users want to open the file in text mode
they can use O_TEXT.
Examples:
@code
/* This example creates a file in the current working directory and
* opens it in read-write mode. */
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
int main()
{
int fd = 0;
fd = open("Example.txt" , O_CREAT | O_EXCL , 0666);
if(fd < 0 )
{
printf("Failed to create and open file in current working directory
");
return -1;
}
printf("File created and opened in current working directory
" );
return 0;
}
@endcode
Output
@code
File created and opened in current working directory
@endcode
@see chmod()
@see close()
@see dup()
@see getdtablesize()
@see lseek()
@see read()
@see umask()
@see write()
@see fopen()
Limitations:
KErrNotReady of Symbian error code is mapped to ENOENT, which typically means drive
not found or filesystem not mounted on the drive.
@capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&) const
@publishedAll
@externallyDefinedApi
*/
/** @fn open64(const char *file, int flags, ...)
@param file
@param flags
@param ...
@return If successful, open64() returns a non-negative integer, termed a file descriptor. It returns
-1 on failure and sets errno to indicate the error.
For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0
@see open()
@publishedAll
@externallyDefinedApi
*/
/**@typedef typedef __off_t off64_t;
Large file offsets.
@publishedAll
@externallyDefinedApi
*/
/** @fn creat(const char *file, mode_t mode)
@param file
@param mode
@return open and creat return the new file descriptor, or -1 if an error occurred (in
which case errno is set appropriately).
This interface is made obsolete by: open
The creat function
is the same as: open(path, O_CREAT | O_TRUNC | O_WRONLY, mode); Limitation :Creating a new file doesn't alter the time stamp of parent directory, created entry has only two time stamps access and modification timestamps.
Creation time stamp of the file is not supported, here accesstime stamp is equal to modification time stamp.
Examples:
@code
/* Detailed description : This test code demonstrates creat system call usage, it creates a
* in current working directory(if file exists then it is truncated. Preconditions : None */
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
int main()
{
int fd = 0;
fd = creat("Example.txt" , 0666);
if(fd < 0 )
{
printf("File creation failed
");
return -1;
}
printf("Example.txt file created
");
return 0;
}
@endcode
Output
@code
Example.txt file created
@endcode
@see open()
Limitations:
KErrNotReady of Symbian error code is mapped to ENOENT, which typically means drive
not found or filesystem not mounted on the drive.
@capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&) const
@publishedAll
@externallyDefinedApi
*/
/** @fn creat64(const char *file, mode_t mode)
@param file
@param mode
@return creat64() returns the new file descriptor, or -1 if an error occurred (in
which case errno is set appropriately).
For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0
@see creat()
@publishedAll
@externallyDefinedApi
*/
/** @fn fcntl(int aFid, int aCmd, ...)
@param aFid
@param aCmd
@param ...
@return Upon successful completion, the value returned depends on cmd as follows: F_DUPFD A new file descriptor. F_GETFD Value of flag (only the low-order bit is defined). F_GETFL Value of flags. F_GETOWN Value of file descriptor owner (Not supported). other Value other than -1. Otherwise, a value of -1 is returned and errno is set to indicate the error.
@code
The fcntl system call provides for control over descriptors. The argument fd is a descriptor to be operated on by cmd as described below. Depending on the value of cmd, fcntl can take an additional third argument int arg.
F_DUPFD Return a new descriptor as follows: Lowest numbered available descriptor greater than or equal to arg. Same object references as the original descriptor. New descriptor shares the same file offset if the object
was a file. Same access mode (read, write or read/write). Same file status flags (i.e., both file descriptors
share the same file status flags). The close-on-exec flag associated with the new file descriptor
is set to remain open across execve
system calls.
Limitations:
The difference between two file descriptors passed must not
be greater than 8. If the difference is greater than 8 then behaviour of
fcntl system call is undefined.F_SELKW flag is not supported because of underlying platform limitations.
F_RDLCK is not supported because the native platform only supports exclusive locks and not shared locks.
@code
O_NONBLOCK Non-blocking I/O; if no data is available to a read system call, or if a write operation would block, the read or
write call returns -1 with the error EAGAIN. (This flag is Not supported for files)
O_APPEND Force each write to append at the end of file;
corresponds to the O_APPEND flag of open .
(Setting this flag in fcntl currently has no effect on subsequent write system calls)
O_DIRECT Minimize or eliminate the cache effects of reading and writing. The system
will attempt to avoid caching data during read or write. If it cannot avoid
caching the data it will minimize the impact the data has on the cache.
Use of this flag can drastically reduce performance if not used with care
(Not supported).
O_ASYNC Enable the SIGIO signal to be sent to the process group when I/O is possible,
e.g. upon availability of data to be read (Not supported).
F_GETLK Get the first lock that blocks the lock description pointed to by the
third argument, arg, taken as a pointer to a struct flock (see above).
The information retrieved overwrites the information passed to fcntl in the flock structure.
If no lock is found that would prevent this lock from being created,
the structure is left unchanged by this system call except for the
lock type which is set to F_UNLCK .
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 a struct flock (see above).
F_SETLK is used to establish shared (or read) locks ( F_RDLCK )( "F_RDLCK" is not supported)
or exclusive (or write) locks, ( F_WRLCK, ) as well as remove either type of lock ( F_UNLCK. )
If a shared or exclusive lock cannot be set, fcntl returns immediately with EAGAIN. (Not supported)
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 waits until the request can be satisfied.(Not Supported)
If a signal that is to be caught is received while fcntl is waiting for a region, the fcntl will be interrupted if the signal handler has not specified the SA_RESTART . (Not supported)
@endcode
The fcntl system call provides for control over descriptors.
The argument fd is a descriptor to be operated on by cmd as described below.
Depending on the value of cmd, fcntl can take an additional third argument int arg . F_DUPFD Return a new descriptor as follows:
Lowest numbered available descriptor greater than or equal to arg. Same object references as the original descriptor. New descriptor shares the same file offset if the object
was a file. Same access mode (read, write or read/write). Same file status flags (i.e., both file descriptors
share the same file status flags). The close-on-exec flag associated with the new file descriptor
is set to remain open across execve
system calls. Limitation: The difference between two file descriptors passed must not
be greater than 8. If the difference is greater than 8 then behaviour of
fcntl system call is undefined. F_GETFD Get the close-on-exec flag associated with the file descriptor fd as FD_CLOEXEC. If the returned value ANDed with FD_CLOEXEC is 0 the file will remain open across exec, otherwise the file will be closed upon execution of exec (arg is ignored). F_SETFD Set the close-on-exec flag associated with fd to arg, where arg is either 0 or FD_CLOEXEC, as described above. F_GETFL Get descriptor status flags, as described below (arg is ignored). F_SETFL Set descriptor status flags to arg . F_GETOWN Get the process ID or process group currently receiving SIGIO and SIGURG signals. Process groups are returned as negative values (arg is ignored)(Not supported). F_SETOWN Set the process or process group to receive SIGIO and SIGURG signals. Process groups are specified by supplying arg as negative, otherwise arg is interpreted as a process ID (Not supported).
The flags for the F_GETFL and F_SETFL flags are as follows: O_NONBLOCK No n-blocking I/O; if no data is available to a read system call, or if a write operation would block, the read or
write call returns -1 with the error EAGAIN. (This flag is Not supported for files) O_APPEND Force each write to append at the end of file;
corresponds to the O_APPEND flag of open .
(Setting this flag in fcntl currently has no effect on subsequent write system calls) O_DIRECT Minimize or eliminate the cache effects of reading and writing. The system
will attempt to avoid caching data during read or write. If it cannot avoid
caching the data it will minimize the impact the data has on the cache.
Use of this flag can drastically reduce performance if not used with care
(Not supported). O_ASYNC Enable the SIGIO signal to be sent to the process group when I/O is possible,
e.g. upon availability of data to be read (Not supported).
Several commands are available for doing advisory file locking;
they all operate on the following structure:
@code
struct flock {
off_tl_start;/* starting offset */
off_tl_len;/* len = 0 means until end of file */
pid_tl_pid;/* lock owner */
shortl_type;/* lock type: read/write, etc. */
shortl_whence;/* type of l_start */
};
@endcode
The commands available for advisory record locking are as follows:
F_GETLK Get the first lock that blocks the lock description pointed to by the
third argument, arg, taken as a pointer to a struct flock (see above).
The information retrieved overwrites the information passed to fcntl in the flock structure.
If no lock is found that would prevent this lock from being created,
the structure is left unchanged by this system call except for the
lock type which is set to F_UNLCK .
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 a struct flock (see above).
F_SETLK is used to establish shared (or read) locks ( F_RDLCK ) . Note "F_RDLCK" is not supported)
or exclusive (or write) locks, ( F_WRLCK, ) as well as remove either type of lock ( F_UNLCK. )
If a shared or exclusive lock cannot be set, fcntl returns immediately with EAGAIN. (Not supported)
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 waits until the request can be satisfied.
If a signal that is to be caught is received while fcntl is waiting for a region, the fcntl will be interrupted if the signal handler has not specified the SA_RESTART . (Not supported)
When a shared lock has been set on a segment of a file,other processes can 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 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 was not opened with write access.
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.
If l_len is negative, l_start means end edge of the region.
The l_pid field is only used with F_GETLK to return the process ID of the process holding a blocking lock .( Not Supported )
After a successful F_GETLK request, the value of l_whence is SEEK_SET.
Locks may start and extend beyond the current end of a file,
but may not start or extend before the beginning of the file.
A lock is set to extend to the largest possible value of the
file offset for that file if l_len is set to zero.
If l_whence and l_start point to the beginning of the file, and l_len is zero, the entire file is locked.
If an application wishes only to do entire file locking, the flock system call is much more efficient.
There is at most one type of lock set for each byte in the file.
Before a successful return from an F_SETLK or an F_SETLKW ( Not Supported ) 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 is replaced by the new lock type.
As specified above under the descriptions
of shared locks and exclusive locks, an F_SETLK or an F_SETLKW request fails or blocks respectively when another process has existing
locks on bytes in the specified region and the type of any of those
locks conflicts with the type specified in the request.
This interface follows the completely stupid [sic] semantics of System
V and -p1003.1-88 that require that all locks associated with a file for a
given process are removed when any file descriptor for that file is closed by that process. This semantic
means that applications must be aware of any files that a subroutine library
may access. For example if an application for updating the password file locks
the password file database while making the update, and then calls getpwnam to retrieve a record, the lock will
be lost because getpwnam opens, reads, and closes the password
database. The database close will release all locks that the process has associated
with the database, even if the library routine never requested a lock on the
database. Another minor semantic problem with this interface is that locks are
not inherited by a child process created using the fork system
call. The flock interface has much more rational last close semantics and allows locks to be
inherited by child processes. The flock system call is recommended for applications that want to ensure the integrity
of their locks when using library routines or wish to pass locks to their children.
The fcntl, flock ,
and lockf locks are compatible.
Processes using different locking interfaces can cooperate
over the same file safely.
However, only one of such interfaces should be used within
the same process.
If a file is locked by a process through flock ,
any record within the file will be seen as locked
from the viewpoint of another process using fcntl or lockf ,
and vice versa.
Note that fcntl (F_GETLK); returns -1 in l_pid if the process holding a blocking lock previously locked the
file descriptor by flock .
All locks associated with a file for a given process are
removed when the process terminates.
All locks obtained before a call to execve remain in effect until the new program releases them.
If the new program does not know about the locks, they will not be
released until the program exits.
A potential for deadlock occurs if a process controlling a locked region
is put to sleep by attempting to lock the locked region of another process.
This implementation detects that sleeping until a locked region is unlocked
would cause a deadlock and fails with an EDEADLK error.
If 'aFid' corresponds to a shared memory object the only values of cmd that are supported are
F_DUPFD, F_GETFD, F_SETFD, F_SETFL, F_GETFL.
Examples:
@code
/* Detailed description : Sample usafe of fcntl system call */
#include <stdio.h>
#include <fcntl.h>
int main()
{
int fd = 0;
int flags = 0;
fd = open("Example.txt " , O_CREAT | O_RDWR , 0666);
if(fd < 0 )
{
printf("Failed to open file Example.txt
");
return -1;
}
if( (flags = fcntl(fd , F_GETFL) ) < 0 )
{
printf("Fcntl system call failed
");
return -1;
}
printf("Flags of the file %o
" , flags);
return 0;
}
@endcode
Output
@code
Flags of the file 2
@endcode
@see close()
@see flock()
@see getdtablesize()
@see open()
@publishedAll
@externallyDefinedApi
*/
/** @def O_RDONLY
open for reading only
@publishedAll
@externallyDefinedApi
*/
/** @def O_WRONLY
open for writing only
@publishedAll
@externallyDefinedApi
*/
/** @def O_RDWR
open for reading and writing
@publishedAll
@externallyDefinedApi
*/
/** @def O_ACCMODE
mask for above modes
@publishedAll
@externallyDefinedApi
*/
/** @def O_NONBLOCK
no delay
@publishedAll
@externallyDefinedApi
*/
/** @def O_APPEND
set append mode
@publishedAll
@externallyDefinedApi
*/
/** @def O_CREAT
create if nonexistent
@publishedAll
@externallyDefinedApi
*/
/** @def O_TRUNC
truncate to zero length
@publishedAll
@externallyDefinedApi
*/
/** @def O_EXCL
error if already exists
@publishedAll
@externallyDefinedApi
*/
/** @def O_NOCTTY
don't assign controlling terminal
@publishedAll
@externallyDefinedApi
*/
/** @def F_DUPFD
Duplicate file descriptor.
@publishedAll
@externallyDefinedApi
*/
/** @def F_GETFD
Get file descriptor flags.
@publishedAll
@externallyDefinedApi
*/
/** @def F_SETFD
set file descriptor flags
@publishedAll
@externallyDefinedApi
*/
/** @def F_GETFL
get file status flags
@publishedAll
@externallyDefinedApi
*/
/** @def F_SETFL
set file status flags
@publishedAll
@externallyDefinedApi
*/
/** @def F_GETOWN
get SIGIO/SIGURG proc/pgrp
@publishedAll
@externallyDefinedApi
*/
/** @def F_SETOWN
set SIGIO/SIGURG proc/pgrp
@publishedAll
@externallyDefinedApi
*/
/** @def F_GETLK
get record locking information
@publishedAll
@externallyDefinedApi
*/
/** @def F_SETLK
set record locking information
@publishedAll
@externallyDefinedApi
*/
/** @def F_SETLKW
F_SETLK; wait if blocked
@publishedAll
@externallyDefinedApi
*/
/** @def F_GETLK64
get record locking information of large file
@publishedAll
@externallyDefinedApi
*/
/** @def F_SETLK64
set record locking information to a large file
@publishedAll
@externallyDefinedApi
*/
/** @def F_SETLKW64
F_SETLK; wait if blocked in a large file
@publishedAll
@externallyDefinedApi
*/
/** @def F_RDLCK
shared or read lock
@publishedAll
@externallyDefinedApi
*/
/** @def F_UNLCK
unlock
@publishedAll
@externallyDefinedApi
*/
/** @def F_WRLCK
exclusive or write lock
@publishedAll
@externallyDefinedApi
*/
/** @def O_SYNC
POSIX synonym for O_FSYNC
@publishedAll
@externallyDefinedApi
*/
/** @def FD_CLOEXEC
close-on-exec flag
@publishedAll
@externallyDefinedApi
*/
/** @def FREAD
Kernel encoding of open mode; separate read and write bits that are independently testable: 1 greater than the above.
FREAD and FWRITE are excluded from the #ifdef _KERNEL so that TIOCFLUSH, which was documented to use FREAD/FWRITE, continues to work.
@publishedAll
@externallyDefinedApi
*/
/** @def FWRITE
Kernel encoding of open mode; separate read and write bits that are independently testable: 1 greater than the above.
FREAD and FWRITE are excluded from the #ifdef _KERNEL so that TIOCFLUSH, which was documented to use FREAD/FWRITE, continues to work.
@publishedAll
@externallyDefinedApi
*/