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