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

4.104.114.84.95
Last change on this file since e86236b was e86236b, checked in by Joel Sherrill <joel.sherrill@…>, on 06/30/00 at 12:49:40

Added fchdir().

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