source: rtems-docs/posix-users/files_and_directory.rst @ e52906b

5
Last change on this file since e52906b was e52906b, checked in by Sebastian Huber <sebastian.huber@…>, on 01/09/19 at 15:14:06

Simplify SPDX-License-Identifier comment

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