/** @file  ../include/unistd.h

@internalComponent

*/

/** @fn  access(const char *fn, int flags)

@param fn

@param flags

@return   Upon successful completion, the value 0 is returned; otherwise the

value -1 is returned and the global variable errno is set to indicate the

error.

  The access system calls check the accessibility of the file named in the fn argument for the access permissions indicated by the flags argument.

 The value of flags is either the bitwise-inclusive OR of the access permissions to be 

checked (R_OK for read permission, W_OK for write permission, and X_OK for execute/search permission), or the existence test ( F_OK. )

 For additional information on file access permissions see File Access Permissions.

Examples:

@code

/* Detailed description: This sample code checks read-ok accessibility of file Example.c

 *

 * Precondtions: Example.txt file should be present in working directory.

 */

#include <unistd.h>

int main()

{

  if(access("Example.c" ,R_OK)  < 0)  

  {

    printf("Read operation on the file is not permitted") ;

    return -1 ;

  }

  printf("Read operation permitted on Example.c file") ;

  return 0 ;

}

@endcode

 Output

@code

Read operation permitted on Example.c file

@endcode

Limitations:

The fn parameter should not exceed 256 characters in length. 

KErrNotReady of Symbian error code is mapped to ENOENT, which typically means drive

not found or filesystem not mounted on the drive.

@see chmod()

@see stat()

@capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&)

@publishedAll

@externallyDefinedApi

*/

/** @fn  chdir(const char *_path)

@param _path

Note: This description also covers the following functions -

 fchdir() 

@return   Upon successful completion, the value 0 is returned; otherwise the

value -1 is returned and the global variable errno is set to indicate the

error.

  The path argument points to the pathname of a directory.

The chdir system call

causes the named directory

to become the current working directory, that is,

the starting point for path searches of pathnames not beginning with a slash, ‘/.’

 The fchdir system call causes the directory referenced by the file descriptor fd to become the current working directory, the starting point for path 

  searches of pathnames not beginning with a slash, ‘/.’

Examples:

@code

/*

 *  Detailed description   : This test code demonstrates usage of chdir system call

 *

 *  Preconditions : "Example" directory should be present in current working

   directory.

 */

#include <unistd.h>

int main()

{

  if(chdir("Example") < 0 )  

  {

     printf("Failed to change working directory");

     return -1 ;

  }

  printf("Working directory changed");

  return 0 ;

}

@endcode

 Output

@code

Working directory changed

@endcode

@code

#include<unistd.h>

#include<stdio.h>

int test_fchdir()

{

   int retVal;

   int rmdr;

   int mkdr = mkdir("test_dir", S_IWUSR);

   if( !mkdr )

   {

     int opn = open("test_dir", O_RDONLY);

     if( opn != -1 )

     {

       retVal = fchdir( opn );

       if( !retVal )

       {

         printf("Fchdir passed");

       }

       else

       {

         printf("Failed");

       }

       int cls = close(opn);

     }

     else

     {

       printf("Failed");

     }

     rmdr = rmdir("test_dir");  

   }

   else

   {

     printf("Failed");

   }

}

@endcode

 Output

@code

Fchdir passed

@endcode

Limitations:

The path parameter should not exceed 256 characters in length. 

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::SetSessionPath(const TDesC16&)

@capability Deferred @ref RFs::Att(const TDesC16&, unsigned&)

@publishedAll

@externallyDefinedApi

*/

/** @fn  chown(const char *path, uid_t owner, gid_t group)

@param path

@param owner

@param group

Note: This description also covers the following functions -

 lchown() 

@return   These functions always return 0.

 The chown and lchown functions are build supported but not available functionally.

 Symbian OS does not support the concepts of multiple users and groups.

Limitations:

KErrNotReady of symbian error code is mapped to ENOENT, which typically means drive

not found or filesystem not mounted on the drive.

@publishedAll

@externallyDefinedApi

*/

/** @fn  close(int fd)

@param fd

@return   The close() function returns the value 0 if successful; otherwise it returns 

the value -1 and sets the global variable errno to indicate the error.

  The close system call deletes a descriptor from the per-process object reference 

table. If this is the last reference to the underlying object the object will 

be deactivated. For example, on the last close of a file the current seek pointer associated with the file is lost; on the last close of a socket any file descriptor for that file is closed by that process.

If 'fd' refers to a shared memory object that is still referenced at the last close, the 

contents of the memory object persists till it is unreferenced. 

If this is the last close of the shared memory object and the close results in unreferencing of the memory 

object and the memory object is unlinked, (only in this scenario) the memory object is removed.

 When a process exits all associated file descriptors are freed. As there is 

  a limit on active descriptors per processes the close system call is useful when a large quantity of file descriptors 

  are being handled.

Examples:

@code

/* Detailed description   : This test code demonstrates usage of close  system call

 *

 * Preconditions :  None.

 */

#include <stdio.h>

#include <unistd.h>

#include <sys/types.h>

#include <fcntl.h>

int main()

{

  int fd = 0;

  fd = open("Example.txt" , O_CREAT | O_RDWR , 0666);

  if(fd < 0 ) 

  {

    printf("Failed to open file Example.txt");

    return -1;

  }

 if(close(fd) < 0 )

 {

   printf("Failed to close  file Example.txt");

   return -1;

 }

 printf("File Example.txt closed" );

 return 0;

}

@endcode

 Output

@code

File Example.txt closed

@endcode

@see accept()

@see fcntl()

@see flock()

@see open()

@see pipe()

@see socket()

@see shm_open()

@see shm_unlink()

@publishedAll

@externallyDefinedApi

*/

/** @fn  dup(int aFid)

@param aFid

Note: This description also covers the following functions -

 dup2() 

@return   The value -1 is returned if an error occurs in either call.

The external variable errno indicates the cause of the error.

  The dup system call

duplicates an existing object descriptor and returns its value to

the calling process ( newd = dup (aFid, ).); The argument aFid is a small non-negative integer index in

the per-process descriptor table.

 The new descriptor returned by the call

is the lowest numbered descriptor

currently not in use by the process.

 The object referenced by the descriptor does not distinguish

between aFid and newd in any way.

Thus if newd and aFid are duplicate references to an open

file, read , write and lseek calls all move a single pointer into the file,

and append mode, non-blocking I/O and asynchronous I/O options

are shared between the references.

If a separate pointer into the file is desired, a different

object reference to the file must be obtained by issuing an

additional open system call.

 In dup2, the value of the new descriptor newd is specified.

If this descriptor is already in use and oldd != newd, the descriptor is first deallocated as if the close system call had been used.

If aFid is not a valid descriptor, then newd is not closed.

If aFid == newd and aFid is a valid descriptor, then dup2 is successful, and does nothing.

 Limitation: 

@code

dup2(int oldfd, int newfd); 

@endcode

The return value of dup2 can be different 

  from the one user expected to be (newfd). Users of dup2 must therefor use the 

  return value of dup2 as the new allocated fd rather than the one passed in (newfd). 

  As described above, if dup2 is successful the newfd and return values are the 

  same, .

Examples:

@code

/*

 *Detailed description : Sample usage of dup system call

 */

#include <unistd.h>

#include <fcntl.h>

#include <stdio.h>

int main()

{

  int fd;

  FILE *Fil;

  int Newfd;

  fd = open("Example.txt" , O_CREAT | O_RDWR , 0666);

  if(fd < 0 )  {

     printf("Failed to open file Example.txt");

     return -1;

  }

  Newfd  = dup(fd );

  if(Newfd < 0 ) 

  {

    printf("Failed to duplicate file descriptor");

    return -1 ;

  }

  close(fd);

  close(Newfd);

  printf("New Duped fd is %d" , Newfd);

  return 0;

}

@endcode

 Output

@code

New Duped fd is 4

@endcode

@code

/*

 *Detailed description : Sample usage of dup system call

 */

#include <unistd.h>

#include <fcntl.h>

#include <errno.h>

#include <stdio.h>

int main()

{

  int fd;

  FILE *Fil;

  int Newfd;

  fd = open("Example.txt" , O_CREAT | O_RDWR , 0666);

  if(fd < 0 )  {

     printf("Failed to open file Example.txt");

     return -1;

  }

  Newfd  = dup2(fd  , 4);

  if(Newfd < 0 )  {

    printf("Failed to duplicate file descriptor");

    return -1;

  }

  close(fd);

  close(Newfd);

  printf("New Duped fd is %d" , Newfd);

  return 0;

}

@endcode

 Output

@code

New Duped fd is 4

@endcode

@see accept()

@see close()

@see fcntl()

@see getdtablesize()

@see open()

@see pipe()

@see socket()

@publishedAll

@externallyDefinedApi

*/

/** @fn  dup2(int aFid1, int aFid2)

@param aFid1

@param aFid2

Refer to  dup() for the documentation

@see accept()

@see close()

@see fcntl()

@see getdtablesize()

@see open()

@see pipe()

@see socket()

@publishedAll

@externallyDefinedApi

*/

/** @fn  fpathconf(int fd, int name)

@param fd

@param name

Refer to  pathconf() for the documentation

@publishedAll

@externallyDefinedApi

*/

/** @fn  getcwd(char *_buf, size_t _size)

@param _buf

@param _size

@return   Upon successful completion a pointer to the pathname is returned. Otherwise 

a NULL pointer is returned and the global variable errno is set to indicate the error. In addition, getwd copies the error message associated with errno into the memory referenced by buf.

  The getcwd function copies the absolute pathname of the current working directory

into the memory referenced by buf and returns a pointer to buf. The size argument is the _size, in bytes, of the array referenced by buf.

 If _buf is NULL, space is allocated as indicated by size to store the pathname and the current working directory is

returned as long as the _size bytes are sufficient to hold the working directory name.

This space may later be free’d.

 This routine has traditionally been used by programs to save the

name of a working directory for the purpose of returning to it.

A much faster and less error-prone method of accomplishing this is to

open the current directory ((‘.’) and use the fchdir function to return.

Examples:

@code

#include<unistd.h>

#include<stdio.h>

#include <stdlib.h>

#define BUF_SIZE 100

int main()

{

 //change directory to c:

 int c;

 long size = BUF_SIZE;

 char *buf = NULL;

 char *ptr = NULL;

 c = chdir("c:\");

 buf = (char *)malloc((size_t)size);

 if (buf != NULL && c == 0)

 {

  //call getcwd to fetch teh current directory

  ptr = getcwd(buf, (size_t)size);

  printf("getcwd returned: %s", ptr);

 }

 return 0;

}

@endcode

 Output

@code

getcwd returned: c:

@endcode

Notes:

 The getcwd function

returns the default working directory as c:\\private\\XXXXXXXX (where XXXXXXXX is the UID of the process) as the default session path is

initialised to c:\\private\\current_process'_UID, in case of Symbian OS.

@see chdir()

@see malloc()

@see strerror()

@publishedAll

@externallyDefinedApi

*/

/** @fn  getegid(void)

Refer to  getgid() for the documentation

@publishedAll

@externallyDefinedApi

*/

/** @fn  geteuid(void)

Refer to  getuid() for the documentation

@publishedAll

@externallyDefinedApi

*/

/** @fn  getgid(void)

Note: This description also covers the following functions -

 getegid() 

@return   These functions always return 0.

  getgid and getegid are build supported but not available functionally. Symbian OS 

does not support multiple users and groups.

@publishedAll

@externallyDefinedApi

*/

/** @fn  getgroups(int size, gid_t grouplist[])

@param size

@param grouplist

@return   These functions always return 0.

  The getgroups function build supported but not available functionally. Symbian 

OS does not support multiple users and groups.

@publishedAll

@externallyDefinedApi

*/

/** @fn  getpgrp(void)

Note: This description also covers the following functions -

 getpgid() 

@return   These functions always return 0.

  getpgrp and getpgid are build supported but not available functionally. Symbian OS 

does not support multiple users and groups.

@publishedAll

@externallyDefinedApi

*/

/** @fn  getpid(void)

Note: This description also covers the following functions -

 getppid() 

  The getpid system call returns the process ID of the calling process. Though 

the ID is guaranteed to be unique it should NOT be used for constructing temporary file names for security reasons; 

see mkstemp instead.

 The getppid system call

returns the process ID of the parent

of the calling process.

Examples:

@code

/*

 * Detailed description : Sample usage of getpid system call

 */

#include <unistd.h>

int main() 

{

  pid_t pid ;

  if((pid = getpid()) < 0 ) 

  {

     printf("getpid system call failed") ;

     return -1 ;

  }

  printf("pid of this process is %d " , pid) ;

  return 0 ;

}

@endcode

@publishedAll

@externallyDefinedApi

*/

/** @fn  getppid(void)

Refer to  getpid() for the documentation

@publishedAll

@externallyDefinedApi

*/

/** @fn  getuid(void)

Note: This description also covers the following functions -

 geteuid() 

@return   These functions always return 0.

  getuid and geteuid are build supported but not available functionally. Symbian OS 

does not support multiple users and groups.

@publishedAll

@externallyDefinedApi

*/

/** @fn  isatty(int fd)

@param fd

@return   The isatty returns 1 if fd is an open descriptor connected to a terminal; returns 0 otherwise.

  This function operate on the system file descriptors for character special devices.

 The isatty function

determines if the file descriptor fd refers to a valid

terminal type device.

Examples:

@code

#include<unistd.h>

#include<stdio.h>

#include<fcntl.h> //O_APPEND

int main()

{

 int x = isatty(0); //stdin (fd = 0)

 int y = isatty(1); //stdout (fd = 1)

 int z = isatty(2); //stderr (fd = 2)

 printf("{Expected: 1 1 1} %d %d %d", x, y, z);

 int i = isatty(5); //some invalid fd

 int fd_file = open("c:\some.txt", O_APPEND);

 int j = isatty(fd_file); //valid fd of a text file

 int fd_pipe[3];

 int p = pipe(fd_pipe);

 int k = isatty(fd_pipe[1]); //valid fd of a pipe

 close(fd_file);         

 close(fd_pipe[0]);      

 close(fd_pipe[1]);

 printf("{Expected: 0 0 0} %d %d %d", i, j, k);

 unlink("c:\some.txt");

 return 0;

}

@endcode

 Output

@code

{Expected: 1 1 1} 1 1 1

{Expected: 0 0 0} 0 0 0

@endcode

@see ioctl()

@publishedAll

@externallyDefinedApi

*/

/** @fn  link(const char *oldpath, const char *newpath)

@param oldpath

@param newpath

@return   Returns 0 on successful completion. Otherwise returns -1 and sets errno to indicate the error.

  The link system call atomically creates the specified directory entry (hard 

link) newpath with the attributes of the underlying object pointed at by oldpath. Note that if the link is successful the link count of the underlying 

object is not incremented: On Symbian OS link functionality is simulated and the 

underlying object is not aware of a existing link. Link is supported only on regular files and fifos. It is not on directories. Creation 

of link on a existing link file is not supported.

 If oldpath is removed, the file newpath is also deleted as the platform recognizes the underlying object only by oldpath.

 The object pointed at by the oldpath argument must exist for the hard link to succeed and both oldpath and newpath must be in the same file system. The oldpath argument may not be a directory. Creation time stamp of the file 

  is not supported and access time stamp is equal to modification time stamp. 

  A newly created file will not alter the time stamp of parent directory.

Examples:

@code

/*

 * Detailed description  : Example to create link to a file

 * Precondition : "Parent.txt" should exist in c: drive

 *

 */

#include <unistd.h>

#include <stdio.h>

int main(void)

 {

    if(link("C:\Parent.txt","C:\Link") < 0)

    {

         printf("Link creation to parent file failed");

         return -1;

    }

    printf("Link to parent file created");

    return 0;

 }

@endcode

 Output

@code

Link to parent file created.

@endcode

Limitations:

- The oldpath and newpath parameters of the link() function should not exceed 256 characters in length. 

- P.I.P.S. only simulates link files and does not distinguish between hard and symbolic links.

- KErrNotReady of Symbian error code is mapped to ENOENT, which typically means drive

not found or filesystem not mounted on the drive.

@see readlink()

@see symlink()

@see unlink()

@capability Deferred @ref RFs::Delete(const TDesC16&)

@publishedAll

@externallyDefinedApi

*/

/** @fn lseek(int fd, off_t pos, int whence)

@param fd

@param pos

@param whence

@return Upon successful completion,  lseek returns the resulting offset location as measured in bytes from the beginning of the file. Otherwise, a value of -1 is returned and  errno is set to indicate the error.

The  lseek system call repositions the offset of the file descriptor  fildes to the argument  offset according to the directive  whence. The argument  fildes must be an open file descriptor. The  lseek system call repositions the file position pointer associated with the file descriptor  fildes as follows:

	If whence is SEEK_SET, the offset is set to offset bytes.

	If whence is SEEK_CUR, the offset is set to its current location plus offset bytes.

	If whence is SEEK_END, the offset is set to the size of the file plus offset bytes.

Some devices are incapable of seeking. The value of the pointer associated with such a device is undefined.

If 'fd' refers to a shared memory object then lseek() on the shared memory object is supported by the current implementation.

Note : lseek function allows the file offset to be set beyond the existing end-of-file, data in the seeked slot is undefined, and hence the read operation in seeked slot is undefined untill data is actually written into it. lseek beyond existing end-of-file increases the file size accordingly.

Errors:

The  lseek system call will fail and the file position pointer will remain unchanged if:

[EBADF]	The fildes argument is not an open file descriptor.

[EINVAL] 	The whence argument is not a proper value or the resulting file offset would be negative for a non-character special file.

[EOVERFLOW]	The resulting file offset would be a value which cannot be represented correctly in an object of type off_t(Not supported).

[ESPIPE] 	The fildes argument is associated with a pipe, socket, or FIFO.

Examples:

@code

/*

 * Detailed description  : Example for lseek usage.

 */

#include <stdio.h>

#include <sys/stat.h>

#include <fcntl.h>

#include <sys/types.h>

int main()

{

int fd = 0;

 fd = open("lseek.txt"  , O_CREAT | O_RDWR , 0666);

  if(lseek(fd , 0 , SEEK_SET) < 0 ) {

     printf("Lseek on file lseek.txt failed \n");

      return -1;

  }

  printf("Lseek on lseek.txt passed ");

 return 0;

}

@endcode

Output

@code

Lseek on lseek.txt passed

@endcode

@see dup()

@see open()

@publishedAll

@externallyDefinedApi

*/

/** @fn  lseek64(int fildes, off64_t offset, int whence)

@param fildes

@param offset

@param whence

@return   Upon successful completion, lseek64 returns the resulting offset location as measured in bytes from the

beginning of the file.

Otherwise,

a value of -1 is returned and errno is set to indicate

the error.

For full documentation see: http://www.unix.org/version2/whatsnew/lfs20mar.html#3.0

@see lseek()

@publishedAll

@externallyDefinedApi

*/

/** @fn  pathconf(const char *path, int name)

@param path

@param name

Note: This description also covers the following functions -

 fpathconf() 

@return   If the call to pathconf or fpathconf is not successful, -1 is returned and errno is set appropriately.

Otherwise, if the variable is associated with functionality that does

not have a limit in the system, -1 is returned and errno is not modified.

Otherwise, the current variable value is returned.

The pathconf and fpathconf system calls provide a method for applications to determine the current

value of a configurable system limit or option variable associated

with a pathname or file descriptor.

For pathconf, the path argument is the name of a file or directory.

For fpathconf, the fd argument is an open file descriptor.

The name argument specifies the system variable to be queried.

Symbolic constants for each name value are found in the include file \<unistd.h\>.

 The available values are as follows:

@code

 _PC_LINK_MAX

 	The maximum file link count.

_PC_MAX_CANON

 	The maximum number of bytes in terminal canonical input line.

_PC_MAX_INPUT

 	The minimum maximum number of bytes for which space is available in a terminal input queue.

_PC_NAME_MAX

 	The maximum number of bytes in a file name.

_PC_PATH_MAX

 	The maximum number of bytes in a pathname.

_PC_PIPE_BUF

 	The maximum number of bytes which will be written atomically to a pipe.

_PC_CHOWN_RESTRICTED

 	Return 1 if appropriate privilege is required for the chown system call, otherwise 0. -p1003.1-2001 requires appropriate privilege in all cases, but this behavior was optional in prior editions of the standard.

_PC_NO_TRUNC

 	Return greater than zero if attempts to use pathname components longer than

.Brq Dv NAME_MAX will result in an [ENAMETOOLONG] error; otherwise, such components will be truncated to

.Brq Dv NAME_MAX. -p1003.1-2001 requires the error in all cases, but this behavior was optional in prior editions of the standard, and some non- POSIX -compliant file systems do not support this behavior.

_PC_VDISABLE

 	Returns the terminal character disabling value.

_PC_ASYNC_IO

 	Return 1 if asynchronous I/O is supported, otherwise 0.

_PC_PRIO_IO

 	Returns 1 if prioritised I/O is supported for this file, otherwise 0.

_PC_SYNC_IO

 	Returns 1 if synchronised I/O is supported for this file, otherwise 0.

_PC_ALLOC_SIZE_MIN

 	Minimum number of bytes of storage allocated for any portion of a file.

_PC_FILESIZEBITS

 	Number of bits needed to represent the maximum file size.

_PC_REC_INCR_XFER_SIZE

 	Recommended increment for file transfer sizes between _PC_REC_MIN_XFER_SIZE and _PC_REC_MAX_XFER_SIZE.

_PC_REC_MAX_XFER_SIZE

 	Maximum recommended file transfer size.

_PC_REC_MIN_XFER_SIZE

 	Minimum recommended file transfer size.

_PC_REC_XFER_ALIGN

 	Recommended file transfer buffer alignment.

_PC_SYMLINK_MAX

 	Maximum number of bytes in a symbolic link.

_PC_ACL_EXTENDED

 	Returns 1 if an Access Control List (ACL) can be set on the specified file, otherwise 0.

_PC_ACL_PATH_MAX

 	Maximum number of ACL entries per file.

_PC_CAP_PRESENT

 	Returns 1 if a capability state can be set on the specified file, otherwise 0.

_PC_INF_PRESENT

 	Returns 1 if an information label can be set on the specified file, otherwise 0.

_PC_MAC_PRESENT

 	Returns 1 if a Mandatory Access Control (MAC) label can be set on the specified file, otherwise 0.

@endcode

Errors:

If any of the following conditions occur, the  pathconf and  fpathconf system calls shall return -1 and set  errno to the corresponding value.

[EINVAL]	The value of the name argument is invalid.

[EINVAL] 	The implementation does not support an association of the variable name with the associated file.

The pathconf system call will fail if:

[ENOTDIR] 	A component of the path prefix is not a directory.

[ENAMETOOLONG] 	A component of a pathname exceeded

.Brq Dv NAME_MAX characters (but see _PC_NO_TRUNC above), or an entire path name exceeded

.Brq Dv PATH_MAX characters.

[ENOENT] 	The named file does not exist.

[EACCES] 	Search permission is denied for a component of the path prefix.

[ELOOP] 	Too many symbolic links were encountered in translating the pathname.

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

The fpathconf system call will fail if:

[EBADF] 	The fd argument is not a valid open file descriptor.

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

Examples:

@code

#include<unistd.h>

#include<stdio.h>

int test_pathconf()

{

   int fp = open("test_pathconf1.txt", O_RDWR|O_CREAT);

   if(fp != -1)

   {

     int n = pathconf("test_pathconf1.txt", _PC_LINK_MAX);

     if( n < _POSIX_LINK_MAX )

     {

       return -1;

     }

     else

     {

       printf("_PC_LINK_MAX value: %d", n);

       printf("Pathconf passed");

       return 0;

     }

   }

   else

   {

     printf("failed");

     return -1;

   }    

}               

@endcode

 Output

@code

_PC_LINK_MAX value: 1

Pathconf passed

@endcode

Note:

@code

 The current implementation of the functions pathconf and fpathconf considers only the following configurable variables. _PC_LINK_MAX _PC_MAX_CANON _PC_MAX_INPUT _PC_NAME_MAX _PC_PATH_MAX _PC_PIPE_BUF _PC_CHOWN_RESTRICTED _PC_NO_TRUNC _PC_VDISABLE   Also, these functions return the limits as required by the POSIX

standard instead of the actual system limits determined on the run. 

@endcode

@publishedAll

@externallyDefinedApi

*/

/** @fn  pipe(int *fildes)

@param fildes

@return   The pipe function returns the value 0 if successful; otherwise the

value -1 is returned and errno is set to indicate the error.

  The pipe system call

creates a pipe, which is an object allowing

bidirectional data flow,

and allocates a pair of file descriptors.