source: rtems/doc/posix_users/files.t @ e8fd633

4.104.114.84.95
Last change on this file since e8fd633 was 95460cc, checked in by Joel Sherrill <joel.sherrill@…>, on 11/23/99 at 17:07:33

Fixed line too long.

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