source: rtems/doc/new_chapters/files.t @ 9dd23877

4.104.114.84.95
Last change on this file since 9dd23877 was 9dd23877, checked in by Wade A Smith <warm38@…>, on 09/30/98 at 15:40:47

Updated the STATUS CODE section for the truncate routine.

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