Interface status:

externallyDefinedApi

typedef __mode_t mode_t;

Description

Used for some file attributes.

Interface status:

externallyDefinedApi

typedef __off_t off_t;

Description

Used for file sizes.

Interface status:

externallyDefinedApi

typedef __pid_t pid_t;

Description

Used for process IDs and process group IDs.

Interface status:

externallyDefinedApi

IMPORT_C int open(const char *, int,...);

Description

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

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.

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.

Examples:

/* This example creates a file in the current working directory and 
 opens it in read-write mode. */
# 120 "d:/EPOC/release/9.4/common/generic/openenv/core/include/sys/fcntl.dosc" 2
# 121 "d:/EPOC/release/9.4/common/generic/openenv/core/include/sys/fcntl.dosc" 2
# 122 "d:/EPOC/release/9.4/common/generic/openenv/core/include/sys/fcntl.dosc" 2
int main()
{
  int fd = 0;
   fd = open("Example.txt" ,  0x0200  |  0x0800  , 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;
}

Output

File created and opened in current working directory

Limitations:

KErrNotReady of Symbian error code is mapped to ENOENT, which typically means drive not found or filesystem not mounted on the drive.

Parameters

const char * int ...

Return value

int If successful, open returns a non-negative integer, termed a file descriptor. It returns -1 on failure and sets errno to indicate the error.

See also:

• chmod(const char *,mode_t)
• chmod(const char *,mode_t)Sets the access permissions for the file whose name is given by pathname to the ...
• getdtablesize(void)
• getdtablesize(void)...
• lseek(int,off_t,int)
• lseek(int,off_t,int)...
• umask(mode_t)
• umask(mode_t)...
• fopen(const char *,const char *)
• fopen(const char *,const char *)Open a file. Opens the file which name is stored in the filename string and retu...

Interface status:

externallyDefinedApi

IMPORT_C int creat(const char *, mode_t);

Description

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:

/* 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 */
# 181 "d:/EPOC/release/9.4/common/generic/openenv/core/include/sys/fcntl.dosc" 2
# 182 "d:/EPOC/release/9.4/common/generic/openenv/core/include/sys/fcntl.dosc" 2
# 183 "d:/EPOC/release/9.4/common/generic/openenv/core/include/sys/fcntl.dosc" 2
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;
}

Output

Example.txt file created

Limitations:

KErrNotReady of Symbian error code is mapped to ENOENT, which typically means drive not found or filesystem not mounted on the drive.

Parameters

const char * mode_tmode_t

Return value

int open and creat return the new file descriptor, or -1 if an error occurred (in which case errno is set appropriately).

Interface status:

externallyDefinedApi

IMPORT_C int fcntl(int, int,...);

Description

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 . (Not supported)
 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 )
 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)

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 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).

Several commands are available for doing advisory file locking; they all operate on the following structure:

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 */
}; 

The commands available for advisory record locking are as follows: 7 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 2 . (Not supported) 8 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).

8 is used to establish shared (or read) locks ( 1 ) or exclusive (or write) locks, ( 3 , ) as well as remove either type of lock ( 2 . ) If a shared or exclusive lock cannot be set, fcntl returns immediately with EAGAIN. (Not supported) 9 This command is the same as 8 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 7 to return the process ID of the process holding a blocking lock. After a successful 7 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 8 or an 9 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 8 or an 9 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 ( 7 ); 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.

Examples:

/* Detailed description : Sample usafe of fcntl system call */
# 407 "d:/EPOC/release/9.4/common/generic/openenv/core/include/sys/fcntl.dosc" 2
# 408 "d:/EPOC/release/9.4/common/generic/openenv/core/include/sys/fcntl.dosc" 2
int main()
{
  int fd  = 0;
  int flags = 0;
  fd = open("Example.txt " ,  0x0200  |  0x0002   , 0666);
  if(fd < 0 ) 
  {
     printf("Failed to open file Example.txt
");
     return -1;
  }
  if( (flags = fcntl(fd ,  3 ) ) < 0 )  
  {
     printf("Fcntl system call failed 
");
     return -1;
  }
  printf("Flags of the file %o 
" , flags);
  return 0;
}

Output

Flags of the file 2

Parameters

int int ...

Return value

int 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.

See also:

• getdtablesize(void)
• getdtablesize(void)...