/** @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

 */