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

     2 @internalComponent

     3 */

     4 

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

     6 @param fn

     7 @param flags

     8 

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

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

    11 error.

    12 

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

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

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

    16 

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

    18 

    19 Examples:

    20 @code

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

    22  *

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

    24  */

    25 #include <unistd.h>

    26 int main()

    27 {

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

    29   {

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

    31     return -1 ;

    32   }

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

    34   return 0 ;

    35 }

    36 

    37 @endcode

    38  Output

    39 @code

    40 Read operation permitted on Example.c file

    41 

    42 @endcode

    43 

    44 Limitations:

    45 

    46 The fn parameter should not exceed 256 characters in length. 

    47 

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

    49 not found or filesystem not mounted on the drive.

    50 

    51 @see chmod()

    52 @see stat()

    53 

    54 

    55 

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

    57 

    58 @publishedAll

    59 @externallyDefinedApi

    60 */

    61 

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

    63 @param _path

    64 

    65 Note: This description also covers the following functions -

    66  fchdir() 

    67 

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

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

    70 error.

    71 

    72   The path argument points to the pathname of a directory.

    73 The chdir system call

    74 causes the named directory

    75 to become the current working directory, that is,

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

    77 

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

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

    80 

    81 

    82 

    83 Examples:

    84 @code

    85 /*

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

    87  *

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

    89    directory.

    90  */

    91 #include <unistd.h>

    92 int main()

    93 {

    94   if(chdir("Example") < 0 )  

    95   {

    96      printf("Failed to change working directory");

    97      return -1 ;

    98   }

    99   printf("Working directory changed");

   100   return 0 ;

   101 }

   102 

   103 @endcode

   104  Output

   105 @code

   106 Working directory changed

   107 

   108 @endcode

   109 @code

   110 #include<unistd.h>

   111 #include<stdio.h>

   112 int test_fchdir()

   113 {

   114    int retVal;

   115    int rmdr;

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

   117    if( !mkdr )

   118    {

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

   120      if( opn != -1 )

   121      {

   122        retVal = fchdir( opn );

   123        if( !retVal )

   124        {

   125          printf("Fchdir passed");

   126        }

   127        else

   128        {

   129          printf("Failed");

   130        }

   131        int cls = close(opn);

   132      }

   133      else

   134      {

   135        printf("Failed");

   136      }

   137      rmdr = rmdir("test_dir");  

   138    }

   139    else

   140    {

   141      printf("Failed");

   142    }

   143 }

   144 

   145 @endcode

   146  Output

   147 @code

   148 Fchdir passed

   149 

   150 @endcode

   151 

   152 Limitations:

   153 

   154 The path parameter should not exceed 256 characters in length. 

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

   156 not found or filesystem not mounted on the drive.

   157 

   158 @capability Deferred @ref RFs::SetSessionPath(const TDesC16&)

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

   160 

   161 @publishedAll

   162 @externallyDefinedApi

   163 */

   164 

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

   166 @param path

   167 @param owner

   168 @param group

   169 

   170 Note: This description also covers the following functions -

   171  lchown() 

   172 

   173 @return   These functions always return 0.

   174 

   175  

   176 

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

   178 

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

   180 

   181 Limitations:

   182 

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

   184 not found or filesystem not mounted on the drive.

   185 

   186 

   187  

   188 

   189 @publishedAll

   190 @externallyDefinedApi

   191 */

   192 

   193 /** @fn  close(int fd)

   194 @param fd

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

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

   197 

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

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

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

   201 

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

   203 contents of the memory object persists till it is unreferenced. 

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

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

   206 

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

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

   209   are being handled.

   210 

   211 

   212 

   213 Examples:

   214 @code

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

   216  *

   217  * Preconditions :  None.

   218  */

   219 #include <stdio.h>

   220 #include <unistd.h>

   221 #include <sys/types.h>

   222 #include <fcntl.h>

   223 int main()

   224 {

   225   int fd = 0;

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

   227   if(fd < 0 ) 

   228   {

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

   230     return -1;

   231   }

   232  if(close(fd) < 0 )

   233  {

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

   235    return -1;

   236  }

   237  printf("File Example.txt closed" );

   238  return 0;

   239 }

   240 

   241 @endcode

   242  Output

   243 @code

   244 File Example.txt closed

   245 

   246 @endcode

   247 @see accept()

   248 @see fcntl()

   249 @see flock()

   250 @see open()

   251 @see pipe()

   252 @see socket()

   253 @see shm_open()

   254 @see shm_unlink()

   255  

   256 

   257 @publishedAll

   258 @externallyDefinedApi

   259 */

   260 

   261 /** @fn  dup(int aFid)

   262 @param aFid

   263 

   264 Note: This description also covers the following functions -

   265  dup2() 

   266 

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

   268 The external variable errno indicates the cause of the error.

   269 

   270   The dup system call

   271 duplicates an existing object descriptor and returns its value to

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

   273 the per-process descriptor table.

   274 

   275  The new descriptor returned by the call

   276 is the lowest numbered descriptor

   277 currently not in use by the process.

   278 

   279  The object referenced by the descriptor does not distinguish

   280 between aFid and newd in any way.

   281 Thus if newd and aFid are duplicate references to an open

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

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

   284 are shared between the references.

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

   286 object reference to the file must be obtained by issuing an

   287 additional open system call.

   288 

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

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

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

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

   293 

   294  Limitation: 

   295  

   296 @code

   297 dup2(int oldfd, int newfd); 

   298 @endcode

   299 The return value of dup2 can be different 

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

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

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

   303   same, .

   304 

   305 Examples:

   306 @code

   307 /*

   308  *Detailed description : Sample usage of dup system call

   309  */

   310 #include <unistd.h>

   311 #include <fcntl.h>

   312 #include <stdio.h>

   313 int main()

   314 {

   315   int fd;

   316   FILE *Fil;

   317   int Newfd;

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

   319   if(fd < 0 )  {

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

   321      return -1;

   322   }

   323   Newfd  = dup(fd );

   324   if(Newfd < 0 ) 

   325   {

   326     printf("Failed to duplicate file descriptor");

   327     return -1 ;

   328   }

   329   close(fd);

   330   close(Newfd);

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

   332   return 0;

   333 }

   334 

   335 @endcode

   336  Output

   337 @code

   338 New Duped fd is 4

   339 

   340 @endcode

   341 @code

   342 /*

   343  *Detailed description : Sample usage of dup system call

   344  */

   345 #include <unistd.h>

   346 #include <fcntl.h>

   347 #include <errno.h>

   348 #include <stdio.h>

   349 int main()

   350 {

   351   int fd;

   352   FILE *Fil;

   353   int Newfd;

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

   355   if(fd < 0 )  {

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

   357      return -1;

   358   }

   359   Newfd  = dup2(fd  , 4);

   360   if(Newfd < 0 )  {

   361     printf("Failed to duplicate file descriptor");

   362     return -1;

   363   }

   364   close(fd);

   365   close(Newfd);

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

   367   return 0;

   368 }

   369 

   370 @endcode

   371  Output

   372 @code

   373 New Duped fd is 4

   374 

   375 @endcode

   376 @see accept()

   377 @see close()

   378 @see fcntl()

   379 @see getdtablesize()

   380 @see open()

   381 @see pipe()

   382 @see socket()

   383 

   384 

   385  

   386 

   387 @publishedAll

   388 @externallyDefinedApi

   389 */

   390 

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

   392 @param aFid1

   393 @param aFid2

   394 

   395 Refer to  dup() for the documentation

   396 @see accept()

   397 @see close()

   398 @see fcntl()

   399 @see getdtablesize()

   400 @see open()

   401 @see pipe()

   402 @see socket()

   403 

   404 

   405  

   406 

   407 @publishedAll

   408 @externallyDefinedApi

   409 */

   410 

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

   412 @param fd

   413 @param name

   414 

   415 Refer to  pathconf() for the documentation

   416 

   417 

   418  

   419 

   420 @publishedAll

   421 @externallyDefinedApi

   422 */

   423 

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

   425 @param _buf

   426 @param _size

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

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

   429 

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

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

   432 

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

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

   435 This space may later be free’d.

   436 

   437  This routine has traditionally been used by programs to save the

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

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

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

   441 

   442 Examples:

   443 @code

   444 #include<unistd.h>

   445 #include<stdio.h>

   446 #include <stdlib.h>

   447 #define BUF_SIZE 100

   448   

   449 int main()

   450 {

   451  //change directory to c:

   452  int c;

   453  long size = BUF_SIZE;

   454  char *buf = NULL;

   455  char *ptr = NULL;

   456   

   457  c = chdir("c:\");

   458   

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

   460   

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

   462  {

   463   //call getcwd to fetch teh current directory

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

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

   466  }

   467    

   468  return 0;

   469 }

   470 

   471 @endcode

   472  Output

   473 @code

   474 getcwd returned: c:

   475 

   476 @endcode

   477 

   478 Notes:

   479 

   480  The getcwd function

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

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

   483 @see chdir()

   484 @see malloc()

   485 @see strerror()

   486 

   487 

   488  

   489 

   490 @publishedAll

   491 @externallyDefinedApi

   492 */

   493 

   494 /** @fn  getegid(void)

   495 Refer to  getgid() for the documentation

   496 

   497 

   498  

   499 

   500 @publishedAll

   501 @externallyDefinedApi

   502 */

   503 

   504 /** @fn  geteuid(void)

   505 Refer to  getuid() for the documentation

   506 

   507 

   508  

   509 

   510 @publishedAll

   511 @externallyDefinedApi

   512 */

   513 

   514 /** @fn  getgid(void)

   515 

   516 

   517 Note: This description also covers the following functions -

   518  getegid() 

   519 

   520 @return   These functions always return 0.

   521 

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

   523 does not support multiple users and groups.

   524 

   525 

   526 

   527  

   528 

   529 @publishedAll

   530 @externallyDefinedApi

   531 */

   532 

   533 

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

   535 @param size

   536 @param grouplist

   537 @return   These functions always return 0.

   538 

   539   The getgroups function build supported but not available functionally. Symbian 

   540 OS does not support multiple users and groups.

   541 

   542 

   543 

   544 

   545 

   546  

   547 

   548 @publishedAll

   549 @externallyDefinedApi

   550 */

   551 

   552 /** @fn  getpgrp(void)

   553 Note: This description also covers the following functions -

   554  getpgid() 

   555 

   556 @return   These functions always return 0.

   557 

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

   559 does not support multiple users and groups.

   560 

   561 

   562 

   563 

   564 

   565  

   566 

   567 @publishedAll

   568 @externallyDefinedApi

   569 */

   570 

   571 /** @fn  getpid(void)

   572 

   573 Note: This description also covers the following functions -

   574  getppid() 

   575 

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

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

   578 see mkstemp instead.

   579 

   580  The getppid system call

   581 returns the process ID of the parent

   582 of the calling process.

   583 

   584 Examples:

   585 @code

   586 /*

   587  * Detailed description : Sample usage of getpid system call

   588  */

   589 #include <unistd.h>

   590 int main() 

   591 {

   592   pid_t pid ;

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

   594   {

   595      printf("getpid system call failed") ;

   596      return -1 ;

   597   }

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

   599   return 0 ;

   600 }

   601 

   602 @endcode

   603 

   604 

   605  

   606 

   607 @publishedAll

   608 @externallyDefinedApi

   609 */

   610 

   611 /** @fn  getppid(void)

   612 Refer to  getpid() for the documentation

   613 

   614 

   615  

   616 

   617 @publishedAll

   618 @externallyDefinedApi

   619 */

   620 

   621 /** @fn  getuid(void)

   622 Note: This description also covers the following functions -

   623  geteuid() 

   624 

   625 @return   These functions always return 0.

   626 

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

   628 does not support multiple users and groups.

   629 

   630 

   631 

   632  

   633 

   634 @publishedAll

   635 @externallyDefinedApi

   636 */

   637 

   638 /** @fn  isatty(int fd)

   639 @param fd

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

   641 

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

   643 

   644  The isatty function

   645 determines if the file descriptor fd refers to a valid

   646 terminal type device.

   647 

   648 Examples:

   649 @code

   650 #include<unistd.h>

   651 #include<stdio.h>

   652 #include<fcntl.h> //O_APPEND

   653  

   654 int main()

   655 {

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

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

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

   659  

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

   661  

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

   663   

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

   665   

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

   667   

   668  int fd_pipe[3];

   669  int p = pipe(fd_pipe);

   670   

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

   672        

   673  close(fd_file);         

   674  close(fd_pipe[0]);      

   675  close(fd_pipe[1]);

   676       

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

   678  

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

   680  

   681  return 0;

   682 }

   683 

   684 @endcode

   685  Output

   686 @code

   687 {Expected: 1 1 1} 1 1 1

   688 {Expected: 0 0 0} 0 0 0

   689 

   690 @endcode

   691 @see ioctl()

   692 

   693 

   694  

   695 

   696 @publishedAll

   697 @externallyDefinedApi

   698 */

   699 

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

   701 @param oldpath

   702 @param newpath

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

   704 

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

   706 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 

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

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

   709 of link on a existing link file is not supported.

   710 

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

   712 

   713  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 

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

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

   716 

   717 Examples:

   718 @code

   719 /*

   720  * Detailed description  : Example to create link to a file

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

   722  *

   723  */

   724 #include <unistd.h>

   725 #include <stdio.h>

   726 int main(void)

   727  {

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

   729     {

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

   731          return -1;

   732     }

   733     printf("Link to parent file created");

   734     return 0;

   735  }

   736 

   737 @endcode

   738  Output

   739 @code

   740 Link to parent file created.

   741 

   742 @endcode

   743 

   744 Limitations:

   745 

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

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

   748 

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

   750 not found or filesystem not mounted on the drive.

   751 

   752 @see readlink()

   753 @see symlink()

   754 @see unlink()

   755 

   756 

   757 

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

   759 

   760 @publishedAll

   761 @externallyDefinedApi

   762 */

   763 

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

   765 @param fd

   766 @param pos

   767 @param whence

   768 @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.

   769 

   770 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:

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

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

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

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

   775 

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

   777 

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

   779 

   780 Errors:

   781 

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

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

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

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

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

   787 

   788 Examples:

   789 @code

   790 /*

   791  * Detailed description  : Example for lseek usage.

   792  */

   793 #include <stdio.h>

   794 #include <sys/stat.h>

   795 #include <fcntl.h>

   796 #include <sys/types.h>

   797 int main()

   798 {

   799 int fd = 0;

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

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

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

   803       return -1;

   804   }

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

   806  return 0;

   807 }

   808 

   809 @endcode

   810 Output

   811 @code

   812 Lseek on lseek.txt passed

   813 @endcode

   814 

   815 @see dup()

   816 @see open()

   817 

   818  

   819 

   820 @publishedAll

   821 @externallyDefinedApi

   822 */

   823 

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

   825 @param fildes

   826 @param offset

   827 @param whence

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

   829 beginning of the file.

   830 Otherwise,

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

   832 the error.

   833 

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

   835 

   836 @see lseek()

   837  

   838 

   839 @publishedAll

   840 @externallyDefinedApi

   841 */

   842 

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

   844 @param path

   845 @param name

   846 

   847 Note: This description also covers the following functions -

   848  fpathconf() 

   849 

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

   851 Otherwise, if the variable is associated with functionality that does

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

   853 Otherwise, the current variable value is returned.

   854 

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

   856 value of a configurable system limit or option variable associated

   857 with a pathname or file descriptor.

   858 

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

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

   861 The name argument specifies the system variable to be queried.

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

   863 

   864  The available values are as follows:

   865 @code

   866  _PC_LINK_MAX

   867  	The maximum file link count.

   868 _PC_MAX_CANON

   869  	The maximum number of bytes in terminal canonical input line.

   870 _PC_MAX_INPUT

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

   872 _PC_NAME_MAX

   873  	The maximum number of bytes in a file name.

   874 _PC_PATH_MAX

   875  	The maximum number of bytes in a pathname.

   876 _PC_PIPE_BUF

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

   878 _PC_CHOWN_RESTRICTED

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

   880 _PC_NO_TRUNC

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

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

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

   884 _PC_VDISABLE

   885  	Returns the terminal character disabling value.

   886 _PC_ASYNC_IO

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

   888 _PC_PRIO_IO

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

   890 _PC_SYNC_IO

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

   892 _PC_ALLOC_SIZE_MIN

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

   894 _PC_FILESIZEBITS

   895  	Number of bits needed to represent the maximum file size.

   896 _PC_REC_INCR_XFER_SIZE

   897  	Recommended increment for file transfer sizes between _PC_REC_MIN_XFER_SIZE and _PC_REC_MAX_XFER_SIZE.

   898 _PC_REC_MAX_XFER_SIZE

   899  	Maximum recommended file transfer size.

   900 _PC_REC_MIN_XFER_SIZE

   901  	Minimum recommended file transfer size.

   902 _PC_REC_XFER_ALIGN

   903  	Recommended file transfer buffer alignment.

   904 _PC_SYMLINK_MAX

   905  	Maximum number of bytes in a symbolic link.

   906 _PC_ACL_EXTENDED

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

   908 _PC_ACL_PATH_MAX

   909  	Maximum number of ACL entries per file.

   910 _PC_CAP_PRESENT

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

   912 _PC_INF_PRESENT

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

   914 _PC_MAC_PRESENT

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

   916 @endcode

   917   

   918 Errors:

   919 

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

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

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

   923 The pathconf system call will fail if:

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

   925 [ENAMETOOLONG] 	A component of a pathname exceeded

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

   927 .Brq Dv PATH_MAX characters.

   928 [ENOENT] 	The named file does not exist.

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

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

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

   932 The fpathconf system call will fail if:

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

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

   935 

   936 Examples:

   937 @code

   938 #include<unistd.h>

   939 #include<stdio.h>

   940 int test_pathconf()

   941 {

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

   943    if(fp != -1)

   944    {

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

   946      if( n < _POSIX_LINK_MAX )

   947      {

   948        return -1;

   949      }

   950      else

   951      {

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

   953        printf("Pathconf passed");

   954        return 0;

   955      }

   956    }

   957    else

   958    {

   959      printf("failed");

   960      return -1;

   961    }    

   962 }               

   963 

   964 @endcode

   965  Output

   966 @code

   967 _PC_LINK_MAX value: 1

   968 Pathconf passed

   969 

   970 @endcode

   971 

   972 

   973 Note:

   974 

   975 @code

   976  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

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

   978 @endcode

   979 

   980  

   981 

   982 @publishedAll

   983 @externallyDefinedApi

   984 */

   985 

   986 /** @fn  pipe(int *fildes)

   987 @param fildes

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

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

   990 

   991   The pipe system call

   992 creates a pipe, which is an object allowing

   993 bidirectional data flow,

   994 and allocates a pair of file descriptors.

   995 

   996  By convention, the first descriptor is normally used as the read end of the pipe, and the second is normally the write end, so that data written to fildes[1] appears on (i.e. can be read from) fildes[0]. This allows the output of one thread to be sent to another 

   997   thread: the source's standard output is set up to be the write end of the 

   998   pipe and the sink's standard input is set up to be the read end of the 

   999   pipe. The pipe itself persists until all its associated descriptors are closed.

  1000 

  1001  A pipe that has had an end closed is considered widowed. Writing on such a pipe causes the writing process to fail and errno is set to EPIPE . Widowing a pipe is the only way to deliver end-of-file to a 

  1002   reader: After the reader consumes any buffered data, reading a widowed pipe 

  1003   returns a zero count.

  1004 

  1005 Examples:

  1006 @code

  1007 #include <unistd.h>

  1008 #include <stdio.h>

  1009 

  1010 int main(void)

  1011 {

  1012     int fds[2];

  1013     if (pipe(fds) == -1) {

  1014        printf("Pipe creation failed");

  1015     }

  1016     /* fds[0] - opened for read */

  1017     /* fds[1] - opened for write */

  1018     close(fds[0]);

  1019     close(fds[1]);

  1020     return 0;

  1021 }

  1022 

  1023 @endcode

  1024 @see read()

  1025 @see write()

  1026 

  1027 

  1028  

  1029 

  1030 @publishedAll

  1031 @externallyDefinedApi

  1032 */

  1033 

  1034 /** @fn  read(int fd, void *buf, size_t cnt)

  1035 @param fd

  1036 @param buf

  1037 @param cnt

  1038 

  1039 Note: This description also covers the following functions -

  1040  readv() 

  1041 

  1042 @return   If successful, the number of bytes actually read is returned. Upon reading 

  1043 end-of-file, zero is returned. Otherwise, -1 is returned and the global variable errno is set to indicate the error.

  1044 

  1045   The read system call

  1046 attempts to read cnt bytes of data from the object referenced by the descriptor fd into the buffer pointed to by buf. The readv system call

  1047 performs the same action, but scatters the input data

  1048 into the iovcnt buffers specified by the members of the iov array: iov[0], iov[1], ..., iov[iovcnt-1].

  1049 

  1050  For readv the iovec structure is defined as:

  1051 

  1052  struct iovec {

  1053 void   *iov_base;  // Base address. 

  1054 size_t iov_len;    // Length. 

  1055 };

  1056 

  1057  Each iovec entry specifies the base address and length of an area

  1058 in memory where data should be placed.

  1059 The readv system call

  1060 will always fill an area completely before proceeding

  1061 to the next.

  1062 

  1063  On objects capable of seeking, the read starts at a position

  1064 given by the pointer associated with fd (see lseek )

  1065 Upon return from read, the pointer is incremented by the number of bytes actually read.

  1066 

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

  1068 

  1069  Objects that are not capable of seeking always read from the current

  1070 position.

  1071 The value of the pointer associated with such an

  1072 object is undefined.

  1073 

  1074  Upon successful completion, read, and readv return the number of bytes actually read and placed in the buffer.

  1075 The system guarantees to read the number of bytes requested if

  1076 the descriptor references a normal file that has that many bytes left

  1077 before the end-of-file, but in no other case.

  1078 

  1079 Errors:

  1080 

  1081 The  read, and  readv system calls will succeed unless:

  1082 [EBADF] 	The d argument is not a valid file or socket descriptor open for reading.

  1083 [ECONNRESET]The d argument refers to a socket, and the remote socket end is forcibly closed.

  1084 [EFAULT] 	The buf argument points outside the allocated address space(Not supported).

  1085 [EIO] 	An I/O error occurred while reading from the file system(Not supported).

  1086 [EINTR] 	A read from a slow device was interrupted before any data arrived by the delivery of a signal(Not supported).

  1087 [EINVAL] 	The pointer associated with d was negative.

  1088 [EAGAIN] 	The file was marked for non-blocking I/O, and no data were ready to be read.

  1089 [EISDIR] 	The file descriptor is associated with a directory residing on a file system that does not allow regular read operations on directories (e.g. NFS)(Not supported).

  1090 [EOPNOTSUPP] 	The file descriptor is associated with a file system and file type that do not allow regular read operations on it(Not supported).

  1091 [EOVERFLOW] 	The file descriptor is associated with a regular file, nbytes is greater than 0, offset is before the end-of-file, and offset is greater than or equal to the offset maximum established for this file system(Not supported).

  1092 [EINVAL] 	The value nbytes is greater than INT_MAX.

  1093 In addition, readv and preadv may return one of the following errors:

  1094 [EINVAL] 	The iovcnt argument was less than or equal to 0, or greater than IOV_MAX.

  1095 [EINVAL] 	One of the iov_len values in the iov array was negative.

  1096 [EINVAL] 	The sum of the iov_len values in the iov array overflowed a 32-bit integer.

  1097 [EFAULT] 	Part of the iov array points outside the process’s allocated address space.

  1098 

  1099 Examples:

  1100 @code

  1101 /* Detailed description :This example demonstrates usage of read-system call, this

  1102  * Example reads 10 bytes from a file specified

  1103  *

  1104  * Preconditions: Example.txt file should be present in C: and should contain

  1105  * string Hello World.

  1106  *

  1107  */  

  1108 #include <unistd.h>

  1109 #include <sys/types.h>

  1110 #include <sys/stat.h>

  1111 #include <fcntl.h>

  1112 int main()

  1113 {

  1114   int fd = 0;

  1115   char Buff[12] = {0};

  1116  

  1117   fd = open("C:\Example.txt" , O_RDONLY );

  1118  

  1119   if(fd < 0 )  {

  1120      printf("Failed to open C:\Example.txt file");

  1121      return -1;

  1122   }

  1123  

  1124   if(read(fd , Buff , 11) < 11)   {

  1125      printf("Failed to read specified number of bytes from file");

  1126      return -1;

  1127   }

  1128  

  1129   printf("file contains %s 

  1130 " , Buff);

  1131   return 0;

  1132 }

  1133 

  1134 @endcode

  1135  Output