source: rtems-docs/posix_users/files_and_directory.rst @ 1264a8f

4.115
Last change on this file since 1264a8f was 1264a8f, checked in by Amar Takhar <amar@…>, on 01/17/16 at 05:55:21

Split document into seperate files by section.

  • Property mode set to 100644
File size: 45.0 KB
Line 
1Files and Directories Manager
2#############################
3
4Introduction
5============
6
7The files and directories manager is ...
8
9The directives provided by the files and directories manager are:
10
11- ``opendir`` - Open a Directory
12
13- ``readdir`` - Reads a directory
14
15- ``rewinddir`` - Resets the ``readdir()`` pointer
16
17- ``scandir`` - Scan a directory for matching entries
18
19- ``telldir`` - Return current location in directory stream
20
21- ``closedir`` - Ends directory read operation
22
23- ``getdents`` - Get directory entries
24
25- ``chdir`` - Changes the current working directory
26
27- ``fchdir`` - Changes the current working directory
28
29- ``getcwd`` - Gets current working directory
30
31- ``open`` - Opens a file
32
33- ``creat`` - Create a new file or rewrite an existing one
34
35- ``umask`` - Sets a file creation mask
36
37- ``link`` - Creates a link to a file
38
39- ``symlink`` - Creates a symbolic link to a file
40
41- ``readlink`` - Obtain the name of the link destination
42
43- ``mkdir`` - Makes a directory
44
45- ``mkfifo`` - Makes a FIFO special file
46
47- ``unlink`` - Removes a directory entry
48
49- ``rmdir`` - Delete a directory
50
51- ``rename`` - Renames a file
52
53- ``stat`` - Gets information about a file.
54
55- ``fstat`` - Gets file status
56
57- ``lstat`` - Gets file status
58
59- ``access`` - Check permissions for a file.
60
61- ``chmod`` - Changes file mode
62
63- ``fchmod`` - Changes permissions of a file
64
65- ``chown`` - Changes the owner and/ or group of a file
66
67- ``utime`` - Change access and/or modification times of an inode
68
69- ``ftruncate`` - Truncate a file to a specified length
70
71- ``truncate`` - Truncate a file to a specified length
72
73- ``pathconf`` - Gets configuration values for files
74
75- ``fpathconf`` - Get configuration values for files
76
77- ``mknod`` - Create a directory
78
79Background
80==========
81
82Path Name Evaluation
83--------------------
84
85A pathname is a string that consists of no more than ``PATH_MAX``
86bytes, including the terminating null character. A pathname has an optional
87beginning slash, followed by zero or more filenames separated by slashes.
88If the pathname refers to a directory, it may also have one or more trailing
89slashes. Multiple successive slahes are considered to be the same as
90one slash.
91
92POSIX allows a pathname that begins with precisely two successive slashes to be
93interpreted in an implementation-defined manner. RTEMS does not currently
94recognize this as a special condition. Any number of successive
95slashes is treated the same as a single slash. POSIX requires that
96an implementation treat more than two leading slashes as a single slash.
97
98Operations
99==========
100
101There is currently no text in this section.
102
103Directives
104==========
105
106This section details the files and directories manager’s directives.
107A subsection is dedicated to each of this manager’s directives
108and describes the calling sequence, related constants, usage,
109and status codes.
110
111opendir - Open a Directory
112--------------------------
113.. index:: opendir
114.. index:: open a directory
115
116**CALLING SEQUENCE:**
117
118.. code:: c
119
120    #include <sys/types.h>
121    #include <dirent.h>
122    int opendir(
123    const char \*dirname
124    );
125
126**STATUS CODES:**
127
128*EACCES*
129    Search permission was denied on a component of the path
130    prefix of ``dirname``, or read permission is denied
131
132*EMFILE*
133    Too many file descriptors in use by process
134
135*ENFILE*
136    Too many files are currently open in the system.
137
138*ENOENT*
139    Directory does not exist, or ``name`` is an empty string.
140
141*ENOMEM*
142    Insufficient memory to complete the operation.
143
144*ENOTDIR*
145    ``name`` is not a directory.
146
147**DESCRIPTION:**
148
149This routine opens a directory stream corresponding to the
150directory specified by the ``dirname`` argument. The
151directory stream is positioned at the first entry.
152
153**NOTES:**
154
155The routine is implemented in Cygnus newlib.
156
157readdir - Reads a directory
158---------------------------
159.. index:: readdir
160.. index:: reads a directory
161
162**CALLING SEQUENCE:**
163
164.. code:: c
165
166    #include <sys/types.h>
167    #include <dirent.h>
168    int readdir(
169    DIR \*dirp
170    );
171
172**STATUS CODES:**
173
174*EBADF*
175    Invalid file descriptor
176
177**DESCRIPTION:**
178
179The ``readdir()`` function returns a pointer to a structure ``dirent``
180representing the next directory entry from the directory stream pointed to
181by ``dirp``. On end-of-file, NULL is returned.
182
183The ``readdir()`` function may (or may not) return entries for . or .. Your
184program should tolerate reading dot and dot-dot but not require them.
185
186The data pointed to be ``readdir()`` may be overwritten by another call to``readdir()`` for the same directory stream. It will not be overwritten by
187a call for another directory.
188
189**NOTES:**
190
191If ``ptr`` is not a pointer returned by ``malloc()``, ``calloc()``, or``realloc()`` or has been deallocated with ``free()`` or``realloc()``, the results are not portable and are probably disastrous.
192
193The routine is implemented in Cygnus newlib.
194
195rewinddir - Resets the readdir() pointer
196----------------------------------------
197.. index:: rewinddir
198.. index:: resets the readdir() pointer
199
200**CALLING SEQUENCE:**
201
202.. code:: c
203
204    #include <sys/types.h>
205    #include <dirent.h>
206    void rewinddir(
207    DIR \*dirp
208    );
209
210**STATUS CODES:**
211
212No value is returned.
213
214**DESCRIPTION:**
215
216The ``rewinddir()`` function resets the position associated with
217the directory stream pointed to by ``dirp``. It also causes the
218directory stream to refer to the current state of the directory.
219
220**NOTES:**
221
222NONE
223
224If ``dirp`` is not a pointer by ``opendir()``, the results are
225undefined.
226
227The routine is implemented in Cygnus newlib.
228
229scandir - Scan a directory for matching entries
230-----------------------------------------------
231.. index:: scandir
232.. index:: scan a directory for matching entries
233
234**CALLING SEQUENCE:**
235
236.. code:: c
237
238    #include <dirent.h>
239    int scandir(
240    const char       \*dir,
241    struct dirent \***namelist,
242    int  (\*select)(const struct dirent \*),
243    int  (\*compar)(const struct dirent \**, const struct dirent \**)
244    );
245
246**STATUS CODES:**
247
248*ENOMEM*
249    Insufficient memory to complete the operation.
250
251**DESCRIPTION:**
252
253The ``scandir()`` function scans the directory ``dir``, calling``select()`` on each directory entry. Entries for which ``select()``
254returns non-zero are stored in strings allocated via ``malloc()``,
255sorted using ``qsort()`` with the comparison function ``compar()``,
256and collected in array ``namelist`` which is allocated via ``malloc()``.
257If ``select`` is NULL, all entries are selected.
258
259**NOTES:**
260
261The routine is implemented in Cygnus newlib.
262
263telldir - Return current location in directory stream
264-----------------------------------------------------
265.. index:: telldir
266.. index:: return current location in directory stream
267
268**CALLING SEQUENCE:**
269
270.. code:: c
271
272    #include <dirent.h>
273    off_t telldir(
274    DIR \*dir
275    );
276
277**STATUS CODES:**
278
279*EBADF*
280    Invalid directory stream descriptor ``dir``.
281
282**DESCRIPTION:**
283
284The ``telldir()`` function returns the current location associated with the
285directory stream ``dir``.
286
287**NOTES:**
288
289The routine is implemented in Cygnus newlib.
290
291closedir - Ends directory read operation
292----------------------------------------
293.. index:: closedir
294.. index:: ends directory read operation
295
296**CALLING SEQUENCE:**
297
298.. code:: c
299
300    #include <sys/types.h>
301    #include <dirent.h>
302    int closedir(
303    DIR \*dirp
304    );
305
306**STATUS CODES:**
307
308*EBADF*
309    Invalid file descriptor
310
311**DESCRIPTION:**
312
313The directory stream associated with ``dirp`` is closed.
314The value in ``dirp`` may not be usable after a call to``closedir()``.
315
316**NOTES:**
317
318NONE
319
320The argument to ``closedir()`` must be a pointer returned by``opendir()``. If it is not, the results are not portable and
321most likely unpleasant.
322
323The routine is implemented in Cygnus newlib.
324
325chdir - Changes the current working directory
326---------------------------------------------
327.. index:: chdir
328.. index:: changes the current working directory
329
330**CALLING SEQUENCE:**
331
332.. code:: c
333
334    #include <unistd.h>
335    int chdir(
336    const char \*path
337    );
338
339**STATUS CODES:**
340
341On error, this routine returns -1 and sets ``errno`` to one of
342the following:
343
344*EACCES*
345    Search permission is denied for a directory in a file’s path prefix.
346
347*ENAMETOOLONG*
348    Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
349    in effect.
350
351*ENOENT*
352    A file or directory does not exist.
353
354*ENOTDIR*
355    A component of the specified pathname was not a directory when directory
356    was expected.
357
358**DESCRIPTION:**
359
360The ``chdir()`` function causes the directory named by ``path`` to
361become the current working directory; that is, the starting point for
362searches of pathnames not beginning with a slash.
363
364If ``chdir()`` detects an error, the current working directory is not
365changed.
366
367**NOTES:**
368
369NONE
370
371fchdir - Changes the current working directory
372----------------------------------------------
373.. index:: fchdir
374.. index:: changes the current working directory
375
376**CALLING SEQUENCE:**
377
378.. code:: c
379
380    #include <unistd.h>
381    int fchdir(
382    int fd
383    );
384
385**STATUS CODES:**
386
387On error, this routine returns -1 and sets ``errno`` to one of
388the following:
389
390*EACCES*
391    Search permission is denied for a directory in a file’s path prefix.
392
393*ENAMETOOLONG*
394    Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
395    in effect.
396
397*ENOENT*
398    A file or directory does not exist.
399
400*ENOTDIR*
401    A component of the specified pathname was not a directory when directory
402    was expected.
403
404**DESCRIPTION:**
405
406The ``fchdir()`` function causes the directory named by ``fd`` to
407become the current working directory; that is, the starting point for
408searches of pathnames not beginning with a slash.
409
410If ``fchdir()`` detects an error, the current working directory is not
411changed.
412
413**NOTES:**
414
415NONE
416
417getcwd - Gets current working directory
418---------------------------------------
419.. index:: getcwd
420.. index:: gets current working directory
421
422**CALLING SEQUENCE:**
423
424.. code:: c
425
426    #include <unistd.h>
427    int getcwd( void );
428
429**STATUS CODES:**
430
431*EINVAL*
432    Invalid argument
433
434*ERANGE*
435    Result is too large
436
437*EACCES*
438    Search permission is denied for a directory in a file’s path prefix.
439
440**DESCRIPTION:**
441
442The ``getcwd()`` function copies the absolute pathname of the current
443working directory to the character array pointed to by ``buf``. The``size`` argument is the number of bytes available in ``buf``
444
445**NOTES:**
446
447There is no way to determine the maximum string length that ``fetcwd()``
448may need to return. Applications should tolerate getting ``ERANGE``
449and allocate a larger buffer.
450
451It is possible for ``getcwd()`` to return EACCES if, say, ``login``
452puts the process into a directory without read access.
453
454The 1988 standard uses ``int`` instead of ``size_t`` for the second
455parameter.
456
457open - Opens a file
458-------------------
459.. index:: open
460.. index:: opens a file
461
462**CALLING SEQUENCE:**
463
464.. code:: c
465
466    #include <sys/types.h>
467    #include <sys/stat.h>
468    #include <fcntl.h>
469    int open(
470    const char \*path,
471    int         oflag,
472    mode_t      mode
473    );
474
475**STATUS CODES:**
476
477*EACCES*
478    Search permission is denied for a directory in a file’s path prefix.
479
480*EEXIST*
481    The named file already exists.
482
483*EINTR*
484    Function was interrupted by a signal.
485
486*EISDIR*
487    Attempt to open a directory for writing or to rename a file to be a
488    directory.
489
490*EMFILE*
491    Too many file descriptors are in use by this process.
492
493*ENAMETOOLONG*
494    Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
495    effect.
496
497*ENFILE*
498    Too many files are currently open in the system.
499
500*ENOENT*
501    A file or directory does not exist.
502
503*ENOSPC*
504    No space left on disk.
505
506*ENOTDIR*
507    A component of the specified pathname was not a directory when a directory
508    was expected.
509
510*ENXIO*
511    No such device. This error may also occur when a device is not ready, for
512    example, a tape drive is off-line.
513
514*EROFS*
515    Read-only file system.
516
517**DESCRIPTION:**
518
519The ``open`` function establishes a connection between a file and a file
520descriptor. The file descriptor is a small integer that is used by I/O
521functions to reference the file. The ``path`` argument points to the
522pathname for the file.
523
524The ``oflag`` argument is the bitwise inclusive OR of the values of
525symbolic constants. The programmer must specify exactly one of the following
526three symbols:
527
528*O_RDONLY*
529    Open for reading only.
530
531*O_WRONLY*
532    Open for writing only.
533
534*O_RDWR*
535    Open for reading and writing.
536
537Any combination of the following symbols may also be used.
538
539*O_APPEND*
540    Set the file offset to the end-of-file prior to each write.
541
542*O_CREAT*
543    If the file does not exist, allow it to be created. This flag indicates
544    that the ``mode`` argument is present in the call to ``open``.
545
546*O_EXCL*
547    This flag may be used only if O_CREAT is also set. It causes the call
548    to ``open`` to fail if the file already exists.
549
550*O_NOCTTY*
551    If ``path`` identifies a terminal, this flag prevents that teminal from
552    becoming the controlling terminal for thi9s process. See Chapter 8 for a
553    description of terminal I/O.
554
555*O_NONBLOCK*
556    Do no wait for the device or file to be ready or available. After the file
557    is open, the ``read`` and ``write`` calls return immediately. If the
558    process would be delayed in the read or write opermation, -1 is returned and``errno`` is set to ``EAGAIN`` instead of blocking the caller.
559
560*O_TRUNC*
561    This flag should be used only on ordinary files opened for writing. It
562    causes the file to be tuncated to zero length..
563
564Upon successful completion, ``open`` returns a non-negative file
565descriptor.
566
567**NOTES:**
568
569NONE
570
571creat - Create a new file or rewrite an existing one
572----------------------------------------------------
573.. index:: creat
574.. index:: create a new file or rewrite an existing one
575
576**CALLING SEQUENCE:**
577
578.. code:: c
579
580    #include <sys/types.h>
581    #include <sys/stat.h>
582    #include <fcntl.h>
583    int creat(
584    const char \*path,
585    mode_t      mode
586    );
587
588**STATUS CODES:**
589
590*EEXIST*
591    ``path`` already exists and O_CREAT and O_EXCL were used.
592
593*EISDIR*
594    ``path`` refers to a directory and the access requested involved
595    writing
596
597*ETXTBSY*
598    ``path`` refers to an executable image which is currently being
599    executed and write access was requested
600
601*EFAULT*
602    ``path`` points outside your accessible address space
603
604*EACCES*
605    The requested access to the file is not allowed, or one of the
606    directories in ``path`` did not allow search (execute) permission.
607
608*ENAMETOOLONG*
609    ``path`` was too long.
610
611*ENOENT*
612    A directory component in ``path`` does not exist or is a dangling
613    symbolic link.
614
615*ENOTDIR*
616    A component used as a directory in ``path`` is not, in fact, a
617    directory.
618
619*EMFILE*
620    The process alreadyh has the maximum number of files open.
621
622*ENFILE*
623    The limit on the total number of files open on the system has been
624    reached.
625
626*ENOMEM*
627    Insufficient kernel memory was available.
628
629*EROFS*
630    ``path`` refers to a file on a read-only filesystem and write access
631    was requested
632
633**DESCRIPTION:**
634
635``creat`` attempts to create a file and return a file descriptor for
636use in read, write, etc.
637
638**NOTES:**
639
640NONE
641
642The routine is implemented in Cygnus newlib.
643
644umask - Sets a file creation mask.
645----------------------------------
646.. index:: umask
647.. index:: sets a file creation mask.
648
649**CALLING SEQUENCE:**
650
651.. code:: c
652
653    #include <sys/types.h>
654    #include <sys/stat.h>
655    mode_t umask(
656    mode_t cmask
657    );
658
659**STATUS CODES:**
660
661**DESCRIPTION:**
662
663The ``umask()`` function sets the process file creation mask to ``cmask``.
664The file creation mask is used during ``open()``, ``creat()``, ``mkdir()``,``mkfifo()`` calls to turn off permission bits in the ``mode`` argument.
665Bit positions that are set in ``cmask`` are cleared in the mode of the
666created file.
667
668**NOTES:**
669
670NONE
671
672The ``cmask`` argument should have only permission bits set. All other
673bits should be zero.
674
675In a system which supports multiple processes, the file creation mask is inherited
676across ``fork()`` and ``exec()`` calls. This makes it possible to alter the
677default permission bits of created files. RTEMS does not support multiple processes
678so this behavior is not possible.
679
680link - Creates a link to a file
681-------------------------------
682.. index:: link
683.. index:: creates a link to a file
684
685**CALLING SEQUENCE:**
686
687.. code:: c
688
689    #include <unistd.h>
690    int link(
691    const char \*existing,
692    const char \*new
693    );
694
695**STATUS CODES:**
696
697*EACCES*
698    Search permission is denied for a directory in a file’s path prefix
699
700*EEXIST*
701    The named file already exists.
702
703*EMLINK*
704    The number of links would exceed ``LINK_MAX``.
705
706*ENAMETOOLONG*
707    Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
708    effect.
709
710*ENOENT*
711    A file or directory does not exist.
712
713*ENOSPC*
714    No space left on disk.
715
716*ENOTDIR*
717    A component of the specified pathname was not a directory when a directory
718    was expected.
719
720*EPERM*
721    Operation is not permitted. Process does not have the appropriate priviledges
722    or permissions to perform the requested operations.
723
724*EROFS*
725    Read-only file system.
726
727*EXDEV*
728    Attempt to link a file to another file system.
729
730**DESCRIPTION:**
731
732The ``link()`` function atomically creates a new link for an existing file
733and increments the link count for the file.
734
735If the ``link()`` function fails, no directories are modified.
736
737The ``existing`` argument should not be a directory.
738
739The caller may (or may not) need permission to access the existing file.
740
741**NOTES:**
742
743NONE
744
745symlink - Creates a symbolic link to a file
746-------------------------------------------
747.. index:: symlink
748.. index:: creates a symbolic link to a file
749
750**CALLING SEQUENCE:**
751
752.. code:: c
753
754    #include <unistd.h>
755    int symlink(
756    const char \*topath,
757    const char \*frompath
758    );
759
760**STATUS CODES:**
761
762*EACCES*
763    Search permission is denied for a directory in a file’s path prefix
764
765*EEXIST*
766    The named file already exists.
767
768*ENAMETOOLONG*
769    Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
770    effect.
771
772*ENOENT*
773    A file or directory does not exist.
774
775*ENOSPC*
776    No space left on disk.
777
778*ENOTDIR*
779    A component of the specified pathname was not a directory when a directory
780    was expected.
781
782*EPERM*
783    Operation is not permitted. Process does not have the appropriate priviledges
784    or permissions to perform the requested operations.
785
786*EROFS*
787    Read-only file system.
788
789**DESCRIPTION:**
790
791The ``symlink()`` function creates a symbolic link from the frombath to the
792topath. The symbolic link will be interpreted at run-time.
793
794If the ``symlink()`` function fails, no directories are modified.
795
796The caller may (or may not) need permission to access the existing file.
797
798**NOTES:**
799
800NONE
801
802readlink - Obtain the name of a symbolic link destination
803---------------------------------------------------------
804.. index:: readlink
805.. index:: obtain the name of a symbolic link destination
806
807**CALLING SEQUENCE:**
808
809.. code:: c
810
811    #include <unistd.h>
812    int readlink(
813    const char \*path,
814    char       \*buf,
815    size_t      bufsize
816    );
817
818**STATUS CODES:**
819
820*EACCES*
821    Search permission is denied for a directory in a file’s path prefix
822
823*ENAMETOOLONG*
824    Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
825    effect.
826
827*ENOENT*
828    A file or directory does not exist.
829
830*ENOTDIR*
831    A component of the prefix pathname was not a directory when a directory
832    was expected.
833
834*ELOOP*
835    Too many symbolic links were encountered in the pathname.
836
837*EINVAL*
838    The pathname does not refer to a symbolic link
839
840*EFAULT*
841    An invalid pointer was passed into the ``readlink()`` routine.
842
843**DESCRIPTION:**
844
845The ``readlink()`` function places the symbolic link destination into``buf`` argument and returns the number of characters copied.
846
847If the symbolic link destination is longer than bufsize characters the
848name will be truncated.
849
850**NOTES:**
851
852NONE
853
854mkdir - Makes a directory
855-------------------------
856.. index:: mkdir
857.. index:: makes a directory
858
859**CALLING SEQUENCE:**
860
861.. code:: c
862
863    #include <sys/types.h>
864    #include <sys/stat.h>
865    int mkdir(
866    const char \*path,
867    mode_t      mode
868    );
869
870**STATUS CODES:**
871
872*EACCES*
873    Search permission is denied for a directory in a file’s path prefix
874
875*EEXIST*
876    The name file already exist.
877
878*EMLINK*
879    The number of links would exceed LINK_MAX
880
881*ENAMETOOLONG*
882    Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
883    effect.
884
885*ENOENT*
886    A file or directory does not exist.
887
888*ENOSPC*
889    No space left on disk.
890
891*ENOTDIR*
892    A component of the specified pathname was not a directory when a directory
893    was expected.
894
895*EROFS*
896    Read-only file system.
897
898**DESCRIPTION:**
899
900The ``mkdir()`` function creates a new diectory named ``path``. The
901permission bits (modified by the file creation mask) are set from ``mode``.
902The owner and group IDs for the directory are set from the effective user ID
903and group ID.
904
905The new directory may (or may not) contain entries for.. and .. but is otherwise
906empty.
907
908**NOTES:**
909
910NONE
911
912mkfifo - Makes a FIFO special file
913----------------------------------
914.. index:: mkfifo
915.. index:: makes a fifo special file
916
917**CALLING SEQUENCE:**
918
919.. code:: c
920
921    #include <sys/types.h>
922    #include <sys/stat.h>
923    int mkfifo(
924    const char \*path,
925    mode_t      mode
926    );
927
928**STATUS CODES:**
929
930*EACCES*
931    Search permission is denied for a directory in a file’s path prefix
932
933*EEXIST*
934    The named file already exists.
935
936*ENOENT*
937    A file or directory does not exist.
938
939*ENOSPC*
940    No space left on disk.
941
942*ENOTDIR*
943    A component of the specified ``path`` was not a directory when a directory
944    was expected.
945
946*EROFS*
947    Read-only file system.
948
949**DESCRIPTION:**
950
951The ``mkfifo()`` function creates a new FIFO special file named ``path``.
952The permission bits (modified by the file creation mask) are set from``mode``. The owner and group IDs for the FIFO are set from the efective
953user ID and group ID.
954
955**NOTES:**
956
957NONE
958
959unlink - Removes a directory entry
960----------------------------------
961.. index:: unlink
962.. index:: removes a directory entry
963
964**CALLING SEQUENCE:**
965
966.. code:: c
967
968    #include <unistd.h>
969    int unlink(
970    const char path
971    );
972
973**STATUS CODES:**
974
975*EACCES*
976    Search permission is denied for a directory in a file’s path prefix
977
978*EBUSY*
979    The directory is in use.
980
981*ENAMETOOLONG*
982    Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
983    effect.
984
985*ENOENT*
986    A file or directory does not exist.
987
988*ENOTDIR*
989    A component of the specified ``path`` was not a directory when a directory
990    was expected.
991
992*EPERM*
993    Operation is not permitted. Process does not have the appropriate priviledges
994    or permissions to perform the requested operations.
995
996*EROFS*
997    Read-only file system.
998
999**DESCRIPTION:**
1000
1001The ``unlink`` function removes the link named by ``path`` and decrements the
1002link count of the file referenced by the link. When the link count goes to zero
1003and no process has the file open, the space occupied by the file is freed and the
1004file is no longer accessible.
1005
1006**NOTES:**
1007
1008NONE
1009
1010rmdir - Delete a directory
1011--------------------------
1012.. index:: rmdir
1013.. index:: delete a directory
1014
1015**CALLING SEQUENCE:**
1016
1017.. code:: c
1018
1019    #include <unistd.h>
1020    int rmdir(
1021    const char \*pathname
1022    );
1023
1024**STATUS CODES:**
1025
1026*EPERM*
1027    The filesystem containing ``pathname`` does not support the removal
1028    of directories.
1029
1030*EFAULT*
1031    ``pathname`` points ouside your accessible address space.
1032
1033*EACCES*
1034    Write access to the directory containing ``pathname`` was not
1035    allowed for the process’s effective uid, or one of the directories in``pathname`` did not allow search (execute) permission.
1036
1037*EPERM*
1038    The directory containing ``pathname`` has the stickybit (S_ISVTX)
1039    set and the process’s effective uid is neither the uid of the file to
1040    be delected nor that of the director containing it.
1041
1042*ENAMETOOLONG*
1043    ``pathname`` was too long.
1044
1045*ENOENT*
1046    A dirctory component in ``pathname`` does not exist or is a
1047    dangling symbolic link.
1048
1049*ENOTDIR*
1050    ``pathname``, or a component used as a directory in ``pathname``,
1051    is not, in fact, a directory.
1052
1053*ENOTEMPTY*
1054    ``pathname`` contains entries other than . and .. .
1055
1056*EBUSY*
1057    ``pathname`` is the current working directory or root directory of
1058    some process
1059
1060*EBUSY*
1061    ``pathname`` is the current directory or root directory of some
1062    process.
1063
1064*ENOMEM*
1065    Insufficient kernel memory was available
1066
1067*EROGS*
1068    ``pathname`` refers to a file on a read-only filesystem.
1069
1070*ELOOP*
1071    ``pathname`` contains a reference to a circular symbolic link
1072
1073**DESCRIPTION:**
1074
1075``rmdir`` deletes a directory, which must be empty
1076
1077**NOTES:**
1078
1079NONE
1080
1081rename - Renames a file
1082-----------------------
1083.. index:: rename
1084.. index:: renames a file
1085
1086**CALLING SEQUENCE:**
1087
1088.. code:: c
1089
1090    #include <unistd.h>
1091    int rename(
1092    const char \*old,
1093    const char \*new
1094    );
1095
1096**STATUS CODES:**
1097
1098*EACCES*
1099    Search permission is denied for a directory in a file’s path prefix.
1100
1101*EBUSY*
1102    The directory is in use.
1103
1104*EEXIST*
1105    The named file already exists.
1106
1107*EINVAL*
1108    Invalid argument.
1109
1110*EISDIR*
1111    Attempt to open a directory for writing or to rename a file to be a
1112    directory.
1113
1114*EMLINK*
1115    The number of links would exceed LINK_MAX.
1116
1117*ENAMETOOLONG*
1118    Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
1119    in effect.
1120
1121*ENOENT*
1122    A file or directory does no exist.
1123
1124*ENOSPC*
1125    No space left on disk.
1126
1127*ENOTDIR*
1128    A component of the specified pathname was not a directory when a
1129    directory was expected.
1130
1131*ENOTEMPTY*
1132    Attempt to delete or rename a non-empty directory.
1133
1134*EROFS*
1135    Read-only file system
1136
1137*EXDEV*
1138    Attempt to link a file to another file system.
1139
1140**DESCRIPTION:**
1141
1142The ``rename()`` function causes the file known bo ``old`` to
1143now be known as ``new``.
1144
1145Ordinary files may be renamed to ordinary files, and directories may be
1146renamed to directories; however, files cannot be converted using``rename()``. The ``new`` pathname may not contain a path prefix
1147of ``old``.
1148
1149**NOTES:**
1150
1151If a file already exists by the name ``new``, it is removed. The``rename()`` function is atomic. If the ``rename()`` detects an
1152error, no files are removed. This guarantees that the``rename("x", "x")`` does not remove ``x``.
1153
1154You may not rename dot or dot-dot.
1155
1156The routine is implemented in Cygnus newlib using ``link()`` and``unlink()``.
1157
1158stat - Gets information about a file
1159------------------------------------
1160.. index:: stat
1161.. index:: gets information about a file
1162
1163**CALLING SEQUENCE:**
1164
1165.. code:: c
1166
1167    #include <sys/types.h>
1168    #include <sys/stat.h>
1169    int stat(
1170    const char  \*path,
1171    struct stat \*buf
1172    );
1173
1174**STATUS CODES:**
1175
1176*EACCES*
1177    Search permission is denied for a directory in a file’s path prefix.
1178
1179*EBADF*
1180    Invalid file descriptor.
1181
1182*ENAMETOOLONG*
1183    Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
1184    in effect.
1185
1186*ENOENT*
1187    A file or directory does not exist.
1188
1189*ENOTDIR*
1190    A component of the specified pathname was not a directory when a
1191    directory was expected.
1192
1193**DESCRIPTION:**
1194
1195The ``path`` argument points to a pathname for a file. Read, write, or
1196execute permission for the file is not required, but all directories listed
1197in ``path`` must be searchable. The ``stat()`` function obtains
1198information about the named file and writes it to the area pointed to by``buf``.
1199
1200**NOTES:**
1201
1202NONE
1203
1204fstat - Gets file status
1205------------------------
1206.. index:: fstat
1207.. index:: gets file status
1208
1209**CALLING SEQUENCE:**
1210
1211.. code:: c
1212
1213    #include <sys/types.h>
1214    #include <sys/stat.h>
1215    int fstat(
1216    int          fildes,
1217    struct stat \*buf
1218    );
1219
1220**STATUS CODES:**
1221
1222*EBADF*
1223    Invalid file descriptor
1224
1225**DESCRIPTION:**
1226
1227The ``fstat()`` function obtains information about the file
1228associated with ``fildes`` and writes it to the area pointed
1229to by the ``buf`` argument.
1230
1231**NOTES:**
1232
1233If the filesystem object referred to by ``fildes`` is a
1234link, then the information returned in ``buf`` refers
1235to the destination of that link.  This is in contrast to``lstat()`` which does not follow the link.
1236
1237lstat - Gets file status
1238------------------------
1239.. index:: lstat
1240.. index:: gets file status
1241
1242**CALLING SEQUENCE:**
1243
1244.. code:: c
1245
1246    #include <sys/types.h>
1247    #include <sys/stat.h>
1248    int lstat(
1249    int          fildes,
1250    struct stat \*buf
1251    );
1252
1253**STATUS CODES:**
1254
1255*EBADF*
1256    Invalid file descriptor
1257
1258**DESCRIPTION:**
1259
1260The ``lstat()`` function obtains information about the file
1261associated with ``fildes`` and writes it to the area pointed
1262to by the ``buf`` argument.
1263
1264**NOTES:**
1265
1266If the filesystem object referred to by ``fildes`` is a
1267link, then the information returned in ``buf`` refers
1268to the link itself.  This is in contrast to ``fstat()``
1269which follows the link.
1270
1271The ``lstat()`` routine is defined by BSD 4.3 and SVR4
1272and not included in POSIX 1003.1b-1996.
1273
1274access - Check permissions for a file
1275-------------------------------------
1276.. index:: access
1277.. index:: check permissions for a file
1278
1279**CALLING SEQUENCE:**
1280
1281.. code:: c
1282
1283    #include <unistd.h>
1284    int access(
1285    const char \*pathname,
1286    int         mode
1287    );
1288
1289**STATUS CODES:**
1290
1291*EACCES*
1292    The requested access would be denied, either to the file itself or
1293    one of the directories in ``pathname``.
1294
1295*EFAULT*
1296    ``pathname`` points outside your accessible address space.
1297
1298*EINVAL*
1299    ``Mode`` was incorrectly specified.
1300
1301*ENAMETOOLONG*
1302    ``pathname`` is too long.
1303
1304*ENOENT*
1305    A directory component in ``pathname`` would have been accessible but
1306    does not exist or was a dangling symbolic link.
1307
1308*ENOTDIR*
1309    A component used as a directory in ``pathname`` is not, in fact,
1310    a directory.
1311
1312*ENOMEM*
1313    Insufficient kernel memory was available.
1314
1315**DESCRIPTION:**
1316
1317``Access`` checks whether the process would be allowed to read, write or
1318test for existence of the file (or other file system object) whose name is``pathname``. If ``pathname`` is a symbolic link permissions of the
1319file referred by this symbolic link are tested.
1320
1321``Mode`` is a mask consisting of one or more of R_OK, W_OK, X_OK and F_OK.
1322
1323**NOTES:**
1324
1325NONE
1326
1327chmod - Changes file mode.
1328--------------------------
1329.. index:: chmod
1330.. index:: changes file mode.
1331
1332**CALLING SEQUENCE:**
1333
1334.. code:: c
1335
1336    #include <sys/types.h>
1337    #include <sys/stat.h>
1338    int chmod(
1339    const char \*path,
1340    mode_t      mode
1341    );
1342
1343**STATUS CODES:**
1344
1345*EACCES*
1346    Search permission is denied for a directory in a file’s path prefix
1347
1348*ENAMETOOLONG*
1349    Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
1350    effect.
1351
1352*ENOENT*
1353    A file or directory does not exist.
1354
1355*ENOTDIR*
1356    A component of the specified pathname was not a directory when a directory
1357    was expected.
1358
1359*EPERM*
1360    Operation is not permitted. Process does not have the appropriate priviledges
1361    or permissions to perform the requested operations.
1362
1363*EROFS*
1364    Read-only file system.
1365
1366**DESCRIPTION:**
1367
1368Set the file permission bits, the set user ID bit, and the set group ID bit
1369for the file named by ``path`` to ``mode``. If the effective user ID
1370does not match the owner of the file and the calling process does not have
1371the appropriate privileges, ``chmod()`` returns -1 and sets ``errno`` to``EPERM``.
1372
1373**NOTES:**
1374
1375NONE
1376
1377fchmod - Changes permissions of a file
1378--------------------------------------
1379.. index:: fchmod
1380.. index:: changes permissions of a file
1381
1382**CALLING SEQUENCE:**
1383
1384.. code:: c
1385
1386    #include <sys/types.h>
1387    #include <sys/stat.h>
1388    int fchmod(
1389    int    fildes,
1390    mode_t mode
1391    );
1392
1393**STATUS CODES:**
1394
1395*EACCES*
1396    Search permission is denied for a directory in a file’s path prefix.
1397
1398*EBADF*
1399    The descriptor is not valid.
1400
1401*EFAULT*
1402    ``path`` points outside your accessible address space.
1403
1404*EIO*
1405    A low-level I/o error occurred while modifying the inode.
1406
1407*ELOOP*
1408    ``path`` contains a circular reference
1409
1410*ENAMETOOLONG*
1411    Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
1412    in effect.
1413
1414*ENOENT*
1415    A file or directory does no exist.
1416
1417*ENOMEM*
1418    Insufficient kernel memory was avaliable.
1419
1420*ENOTDIR*
1421    A component of the specified pathname was not a directory when a
1422    directory was expected.
1423
1424*EPERM*
1425    The effective UID does not match the owner of the file, and is not
1426    zero
1427
1428*EROFS*
1429    Read-only file system
1430
1431**DESCRIPTION:**
1432
1433The mode of the file given by ``path`` or referenced by``filedes`` is changed.
1434
1435**NOTES:**
1436
1437NONE
1438
1439getdents - Get directory entries
1440--------------------------------
1441.. index:: getdents
1442.. index:: get directory entries
1443
1444**CALLING SEQUENCE:**
1445
1446.. code:: c
1447
1448    #include <unistd.h>
1449    #include <linux/dirent.h>
1450    #include <linux/unistd.h>
1451    long getdents(
1452    int   dd_fd,
1453    char \*dd_buf,
1454    int   dd_len
1455    );
1456
1457**STATUS CODES:**
1458
1459A successful call to ``getdents`` returns th the number of bytes read.
1460On end of directory, 0 is returned. When an error occurs, -1 is returned,
1461and ``errno`` is set appropriately.
1462
1463*EBADF*
1464    Invalid file descriptor ``fd``.
1465
1466*EFAULT*
1467    Argument points outside the calling process’s address space.
1468
1469*EINVAL*
1470    Result buffer is too small.
1471
1472*ENOENT*
1473    No such directory.
1474
1475*ENOTDIR*
1476    File descriptor does not refer to a directory.
1477
1478**DESCRIPTION:**
1479
1480``getdents`` reads several ``dirent`` structures from the directory
1481pointed by ``fd`` into the memory area pointed to by ``dirp``. The
1482parameter ``count`` is the size of the memory area.
1483
1484**NOTES:**
1485
1486NONE
1487
1488chown - Changes the owner and/or group of a file.
1489-------------------------------------------------
1490.. index:: chown
1491.. index:: changes the owner and/or group of a file.
1492
1493**CALLING SEQUENCE:**
1494
1495.. code:: c
1496
1497    #include <sys/types.h>
1498    #include <unistd.h>
1499    int chown(
1500    const char \*path,
1501    uid_t       owner,
1502    gid_t       group
1503    );
1504
1505**STATUS CODES:**
1506
1507*EACCES*
1508    Search permission is denied for a directory in a file’s path prefix
1509
1510*EINVAL*
1511    Invalid argument
1512
1513*ENAMETOOLONG*
1514    Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
1515    effect.
1516
1517*ENOENT*
1518    A file or directory does not exist.
1519
1520*ENOTDIR*
1521    A component of the specified pathname was not a directory when a directory
1522    was expected.
1523
1524*EPERM*
1525    Operation is not permitted. Process does not have the appropriate priviledges
1526    or permissions to perform the requested operations.
1527
1528*EROFS*
1529    Read-only file system.
1530
1531**DESCRIPTION:**
1532
1533The user ID and group ID of the file named by ``path`` are set to``owner`` and ``path``, respectively.
1534
1535For regular files, the set group ID (S_ISGID) and set user ID (S_ISUID)
1536bits are cleared.
1537
1538Some systems consider it a security violation to allow the owner of a file to
1539be changed, If users are billed for disk space usage, loaning a file to
1540another user could result in incorrect billing. The ``chown()`` function
1541may be restricted to privileged users for some or all files. The group ID can
1542still be changed to one of the supplementary group IDs.
1543
1544**NOTES:**
1545
1546This function may be restricted for some file. The ``pathconf`` function
1547can be used to test the ``_PC_CHOWN_RESTRICTED`` flag.
1548
1549utime - Change access and/or modification times of an inode
1550-----------------------------------------------------------
1551.. index:: utime
1552.. index:: change access and/or modification times of an inode
1553
1554**CALLING SEQUENCE:**
1555
1556.. code:: c
1557
1558    #include <sys/types.h>
1559    int utime(
1560    const char     \*filename,
1561    struct utimbuf \*buf
1562    );
1563
1564**STATUS CODES:**
1565
1566*EACCES*
1567    Permission to write the file is denied
1568
1569*ENOENT*
1570    ``Filename`` does not exist
1571
1572**DESCRIPTION:**
1573
1574``Utime`` changes the access and modification times of the inode
1575specified by ``filename`` to the ``actime`` and ``modtime``
1576fields of ``buf`` respectively. If ``buf`` is NULL, then the
1577access and modification times of the file are set to the current time.
1578
1579**NOTES:**
1580
1581NONE
1582
1583ftruncate - truncate a file to a specified length
1584-------------------------------------------------
1585.. index:: ftruncate
1586.. index:: truncate a file to a specified length
1587
1588**CALLING SEQUENCE:**
1589
1590.. code:: c
1591
1592    #include <unistd.h>
1593    int ftrunctate(
1594    int    fd,
1595    size_t length
1596    );
1597
1598**STATUS CODES:**
1599
1600*ENOTDIR*
1601    A component of the path prefix is not a directory.
1602
1603*EINVAL*
1604    The pathname contains a character with the high-order bit set.
1605
1606*ENAMETOOLONG*
1607    A component of a pathname exceeded 255 characters, or an entire
1608    path name exceeded 1023 characters.
1609
1610*ENOENT*
1611    The named file does not exist.
1612
1613*EACCES*
1614    The named file is not writable by the user.
1615
1616*EACCES*
1617    Search permission is denied for a component of the path prefix.
1618
1619*ELOOP*
1620    Too many symbolic links were encountered in translating the
1621    pathname
1622
1623*EISDIR*
1624    The named file is a directory.
1625
1626*EROFS*
1627    The named file resides on a read-only file system
1628
1629*ETXTBSY*
1630    The file is a pure procedure (shared text) file that is being
1631    executed
1632
1633*EIO*
1634    An I/O error occurred updating the inode.
1635
1636*EFAULT*
1637    ``Path`` points outside the process’s allocated address space.
1638
1639*EBADF*
1640    The ``fd`` is not a valid descriptor.
1641
1642**DESCRIPTION:**
1643
1644``truncate()`` causes the file named by ``path`` or referenced by``fd`` to be truncated to at most ``length`` bytes in size. If the
1645file previously was larger than this size, the extra data is lost. With``ftruncate()``, the file must be open for writing.
1646
1647**NOTES:**
1648
1649NONE
1650
1651truncate - truncate a file to a specified length
1652------------------------------------------------
1653.. index:: truncate
1654.. index:: truncate a file to a specified length
1655
1656**CALLING SEQUENCE:**
1657
1658.. code:: c
1659
1660    #include <unistd.h>
1661    int trunctate(
1662    const char \*path,
1663    size_t      length
1664    );
1665
1666**STATUS CODES:**
1667
1668*ENOTDIR*
1669    A component of the path prefix is not a directory.
1670
1671*EINVAL*
1672    The pathname contains a character with the high-order bit set.
1673
1674*ENAMETOOLONG*
1675    A component of a pathname exceeded 255 characters, or an entire
1676    path name exceeded 1023 characters.
1677
1678*ENOENT*
1679    The named file does not exist.
1680
1681*EACCES*
1682    The named file is not writable by the user.
1683
1684*EACCES*
1685    Search permission is denied for a component of the path prefix.
1686
1687*ELOOP*
1688    Too many symbolic links were encountered in translating the
1689    pathname
1690
1691*EISDIR*
1692    The named file is a directory.
1693
1694*EROFS*
1695    The named file resides on a read-only file system
1696
1697*ETXTBSY*
1698    The file is a pure procedure (shared text) file that is being
1699    executed
1700
1701*EIO*
1702    An I/O error occurred updating the inode.
1703
1704*EFAULT*
1705    ``Path`` points outside the process’s allocated address space.
1706
1707*EBADF*
1708    The ``fd`` is not a valid descriptor.
1709
1710**DESCRIPTION:**
1711
1712``truncate()`` causes the file named by ``path`` or referenced by``fd`` to be truncated to at most ``length`` bytes in size. If the
1713file previously was larger than this size, the extra data is lost. With``ftruncate()``, the file must be open for writing.
1714
1715**NOTES:**
1716
1717NONE
1718
1719pathconf - Gets configuration values for files
1720----------------------------------------------
1721.. index:: pathconf
1722.. index:: gets configuration values for files
1723
1724**CALLING SEQUENCE:**
1725
1726.. code:: c
1727
1728    #include <unistd.h>
1729    int pathconf(
1730    const char \*path,
1731    int         name
1732    );
1733
1734**STATUS CODES:**
1735
1736*EINVAL*
1737    Invalid argument
1738
1739*EACCES*
1740    Permission to write the file is denied
1741
1742*ENAMETOOLONG*
1743    Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC
1744    is in effect.
1745
1746*ENOENT*
1747    A file or directory does not exist
1748
1749*ENOTDIR*
1750    A component of the specified ``path`` was not a directory whan a
1751    directory was expected.
1752
1753**DESCRIPTION:**
1754
1755``pathconf()`` gets a value for the configuration option ``name``
1756for the open file descriptor ``filedes``.
1757
1758The possible values for ``name`` are:
1759
1760*_PC_LINK_MAX*
1761    returns the maximum number of links to the file. If ``filedes`` or``path`` refer to a directory, then the value applies to the whole
1762    directory. The corresponding macro is ``_POSIX_LINK_MAX``.
1763
1764*_PC_MAX_CANON*
1765    returns the maximum length of a formatted input line, where ``filedes``
1766    or ``path`` must refer to a terminal. The corresponding macro is``_POSIX_MAX_CANON``.
1767
1768*_PC_MAX_INPUT*
1769    returns the maximum length of an input line, where ``filedes`` or``path`` must refer to a terminal. The corresponding macro is``_POSIX_MAX_INPUT``.
1770
1771*_PC_NAME_MAX*
1772    returns the maximum length of a filename in the directory ``path`` or``filedes``. The process is allowed to create. The corresponding macro
1773    is ``_POSIX_NAME_MAX``.
1774
1775*_PC_PATH_MAX*
1776    returns the maximum length of a relative pathname when ``path`` or``filedes`` is the current working directory. The corresponding macro
1777    is ``_POSIX_PATH_MAX``.
1778
1779*_PC_PIPE_BUF*
1780    returns the size of the pipe buffer, where ``filedes`` must refer to a
1781    pipe or FIFO and ``path`` must refer to a FIFO. The corresponding macro
1782    is ``_POSIX_PIPE_BUF``.
1783
1784*_PC_CHOWN_RESTRICTED*
1785    returns nonzero if the chown(2) call may not be used on this file. If``filedes`` or ``path`` refer to a directory, then this applies to all
1786    files in that directory. The corresponding macro is``_POSIX_CHOWN_RESTRICTED``.
1787
1788**NOTES:**
1789
1790Files with name lengths longer than the value returned for ``name`` equal``_PC_NAME_MAX`` may exist in the given directory.
1791
1792fpathconf - Gets configuration values for files
1793-----------------------------------------------
1794.. index:: fpathconf
1795.. index:: gets configuration values for files
1796
1797**CALLING SEQUENCE:**
1798
1799.. code:: c
1800
1801    #include <unistd.h>
1802    int fpathconf(
1803    int filedes,
1804    int name
1805    );
1806
1807**STATUS CODES:**
1808
1809*EINVAL*
1810    Invalid argument
1811
1812*EACCES*
1813    Permission to write the file is denied
1814
1815*ENAMETOOLONG*
1816    Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC
1817    is in effect.
1818
1819*ENOENT*
1820    A file or directory does not exist
1821
1822*ENOTDIR*
1823    A component of the specified ``path`` was not a directory whan a
1824    directory was expected.
1825
1826**DESCRIPTION:**
1827
1828``pathconf()`` gets a value for the configuration option ``name``
1829for the open file descriptor ``filedes``.
1830
1831The possible values for name are:
1832
1833*_PC_LINK_MAX*
1834    returns the maximum number of links to the file. If ``filedes`` or``path`` refer to a directory, then the value applies to the whole
1835    directory. The corresponding macro is _POSIX_LINK_MAX.
1836
1837*_PC_MAX_CANON*
1838    returns the maximum length of a formatted input line, where ``filedes``
1839    or ``path`` must refer to a terminal. The corresponding macro is``_POSIX_MAX_CANON``.
1840
1841*_PC_MAX_INPUT*
1842    returns the maximum length of an input line, where ``filedes`` or``path`` must refer to a terminal. The corresponding macro is``_POSIX_MAX_INPUT``.
1843
1844*_PC_NAME_MAX*
1845    returns the maximum length of a filename in the directory ``path`` or``filedes``. The process is allowed to create. The corresponding macro
1846    is ``_POSIX_NAME_MAX``.
1847
1848*_PC_PATH_MAX*
1849    returns the maximum length of a relative pathname when ``path`` or``filedes`` is the current working directory. The corresponding macro
1850    is ``_POSIX_PATH_MAX``.
1851
1852*_PC_PIPE_BUF*
1853    returns the size of the pipe buffer, where ``filedes`` must refer to a
1854    pipe or FIFO and ``path`` must refer to a FIFO. The corresponding macro
1855    is ``_POSIX_PIPE_BUF``.
1856
1857*_PC_CHOWN_RESTRICTED*
1858    returns nonzero if the ``chown()`` call may not be used on this file. If``filedes`` or ``path`` refer to a directory, then this applies to all
1859    files in that directory. The corresponding macro is``_POSIX_CHOWN_RESTRICTED``.
1860
1861**NOTES:**
1862
1863NONE
1864
1865mknod - create a directory
1866--------------------------
1867.. index:: mknod
1868.. index:: create a directory
1869
1870**CALLING SEQUENCE:**
1871
1872.. code:: c
1873
1874    #include <unistd.h>
1875    #include <fcntl.h>
1876    #include <sys/types.h>
1877    #include <sys/stat.h>
1878    long mknod(
1879    const char \*pathname,
1880    mode_t      mode,
1881    dev_t       dev
1882    );
1883
1884**STATUS CODES:**
1885
1886``mknod`` returns zero on success, or -1 if an error occurred (in which case,
1887errno is set appropriately).
1888
1889*ENAMETOOLONG*
1890    ``pathname`` was too long.
1891
1892*ENOENT*
1893    A directory component in ``pathname`` does not exist or is a dangling symbolic
1894    link.
1895
1896*ENOTDIR*
1897    A component used in the directory ``pathname`` is not, in fact, a directory.
1898
1899*ENOMEM*
1900    Insufficient kernel memory was available
1901
1902*EROFS*
1903    ``pathname`` refers to a file on a read-only filesystem.
1904
1905*ELOOP*
1906    ``pathname`` contains a reference to a circular symbolic link, ie a symbolic
1907    link whose expansion contains a reference to itself.
1908
1909*ENOSPC*
1910    The device containing ``pathname`` has no room for the new node.
1911
1912**DESCRIPTION:**
1913
1914``mknod`` attempts to create a filesystem node (file, device special file or
1915named pipe) named ``pathname``, specified by ``mode`` and ``dev``.
1916
1917``mode`` specifies both the permissions to use and the type of node to be created.
1918
1919It should be a combination (using bitwise OR) of one of the file types listed
1920below and the permissions for the new node.
1921
1922The permissions are modified by the process’s ``umask`` in the usual way: the
1923permissions of the created node are ``(mode & ~umask)``.
1924
1925The file type should be one of ``S_IFREG``, ``S_IFCHR``, ``S_IFBLK`` and``S_IFIFO`` to specify a normal file (which will be created empty), character
1926special file, block special file or FIFO (named pipe), respectively, or zero, which
1927will create a normal file.
1928
1929If the file type is ``S_IFCHR`` or ``S_IFBLK`` then ``dev`` specifies the major
1930and minor numbers of the newly created device special file; otherwise it is ignored.
1931
1932The newly created node will be owned by the effective uid of the process. If the
1933directory containing the node has the set group id bit set, or if the filesystem
1934is mounted with BSD group semantics, the new node will inherit the group ownership
1935from its parent directory; otherwise it will be owned by the effective gid of the
1936process.
1937
1938**NOTES:**
1939
1940NONE
1941
1942.. COMMENT: COPYRIGHT (c) 1988-2002.
1943
1944.. COMMENT: On-Line Applications Research Corporation (OAR).
1945
1946.. COMMENT: All rights reserved.
1947
Note: See TracBrowser for help on using the repository browser.