source: rtems/doc/new_chapters/files.t @ 982ed3f8

4.104.114.84.95
Last change on this file since 982ed3f8 was 982ed3f8, checked in by Wade A Smith <warm38@…>, on Sep 29, 1998 at 9:53:08 PM

Made cosmetic changes and documented routines in this file

  • Property mode set to 100644
File size: 40.4 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@itme @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@itme @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
1393@table @b
1394@item E
1395The
1396
1397@end table
1398
1399@subheading DESCRIPTION:
1400
1401@subheading NOTES:
1402
1403NONE
1404
1405@page
1406@subsection chown - Changes the owner and/or group of a file.
1407
1408@subheading CALLING SEQUENCE:
1409
1410@ifset is-C
1411@example
1412#include <sys/types.h>
1413#include <unistd.h>
1414
1415int chown(
1416  const char *path,
1417  uid_t       owner,
1418  gid_t       group
1419);
1420@end example
1421@end ifset
1422
1423@ifset is-Ada
1424@end ifset
1425
1426@subheading STATUS CODES:
1427
1428@table @b
1429@item EACCES
1430Search permission is denied for a directory in a file's path prefix
1431
1432@item EINVAL
1433Invalid argument
1434
1435@item ENAMETOOLONG
1436Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
1437effect.
1438
1439@item ENOENT
1440A file or directory does not exist.
1441
1442@item ENOTDIR
1443A component of the specified pathname was not a directory when a directory
1444was expected.
1445
1446@item EPERM
1447Operation is not permitted.  Process does not have the appropriate priviledges
1448or permissions to perform the requested operations.
1449
1450@item EROFS
1451Read-only file system.
1452
1453@end table
1454
1455@subheading DESCRIPTION:
1456
1457The user ID and group ID of the file named by @code{path} are set to
1458@code{owner} and @code{path}, respectively.
1459
1460For regular files, the set group ID (S_ISGID) and set user ID (S_ISUID)
1461bits are cleared.
1462
1463Some systems consider it a security violation to allow the owner of a file to
1464be changed,  If users are billed for disk space usage, loaning a file to
1465another user could result in incorrect billing.  The @code{chown()} function
1466may be restricted to privileged users for some or all files.  The group ID can
1467still be changed to one of the supplementary group IDs.
1468
1469@subheading NOTES:
1470
1471This function may be restricted for some file.  The @code{pathconf} function
1472can be used to test the @code{_PC_CHOWN_RESTRICTED} flag.
1473
1474
1475
1476@page
1477@subsection utime - Change access and/or modification times of an inode
1478
1479@subheading CALLING SEQUENCE:
1480
1481@ifset is-C
1482@example
1483#include <sys/types.h>
1484
1485int utime(
1486  const char     *filename,
1487  struct utimbuf *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 EACCES
1499Permission to write the file is denied
1500
1501@item ENOENT
1502@code{Filename} does not exist
1503
1504@end table
1505
1506@subheading DESCRIPTION:
1507
1508@code{Utime} changes the access and modification times of the inode
1509specified by @code{filename} to the @code{actime} and @code{modtime}
1510fields of @code{buf} respectively.  If @code{buf} is NULL, then the
1511access and modification times of the file are set to the current time. 
1512
1513@subheading NOTES:
1514
1515NONE
1516
1517@page
1518@subsection ftruncate - truncate a file to a specified length
1519
1520@subheading CALLING SEQUENCE:
1521
1522@ifset is-C
1523@example
1524#include <unistd.h>
1525
1526int ftrunctate(
1527  int     fd,
1528  size_t  length
1529);
1530@end example
1531@end ifset
1532
1533@ifset is-Ada
1534@end ifset
1535
1536@subheading STATUS CODES:
1537
1538@table @b
1539@item ENOTDIR
1540A component of the path prefix is not a directory.
1541
1542@item EINVAL
1543The pathname contains a character with the high-order bit set.
1544
1545@item ENAMETOOLONG
1546A component of a pathname exceeded 255 characters, or an entire
1547path name exceeded 1023 characters.
1548
1549@item ENOENT
1550The named file does not exist.
1551
1552@item EACCES
1553The named file is not writable by the user.
1554
1555@item EACCES
1556Search permission is denied for a component of the path prefix.
1557
1558@item ELOOP
1559Too many symbolic links were encountered in translating the
1560pathname
1561
1562@item EISDIR
1563The named file is a directory.
1564
1565@item EROFS
1566The named file resides on a read-only file system
1567
1568@item ETXTBSY
1569The file is a pure procedure (shared text) file that is being
1570executed
1571
1572@item EIO
1573An I/O error occurred updating the inode.
1574
1575@item EFAULT
1576@code{Path} points outside the process's allocated address space.
1577
1578@item EBADF
1579The @code{fd} is not a valid descriptor.
1580
1581@end table
1582
1583@subheading DESCRIPTION:
1584
1585@code{truncate()} causes the file named by @code{path} or referenced by
1586@code{fd} to be truncated to at most @code{length} bytes in size.  If the 
1587file previously was larger than this size, the extra data is lost.  With
1588@code{ftruncate()}, the file must be open for writing.
1589
1590@subheading NOTES:
1591
1592NONE
1593
1594@page
1595@subsection truncate - truncate a file to a specified length
1596
1597@subheading CALLING SEQUENCE:
1598
1599@ifset is-C
1600@example
1601#include <unistd.h>
1602
1603int trunctate(
1604  const char *path,
1605  size_t      length
1606);
1607@end example
1608@end ifset
1609
1610@ifset is-Ada
1611@end ifset
1612
1613@subheading STATUS CODES:
1614
1615@table @b
1616@item ENOTDIR
1617A component of the path prefix is not a directory.
1618
1619@item EINVAL
1620The pathname contains a character with the high-order bit set.
1621
1622@item ENAMETOOLONG
1623A component of a pathname exceeded 255 characters, or an entire
1624path name exceeded 1023 characters.
1625
1626@item ENOENT
1627The named file does not exist.
1628
1629@item EACCES
1630The named file is not writable by the user.
1631
1632@item EACCES
1633Search permission is denied for a component of the path prefix.
1634
1635@item ELOOP
1636Too many symbolic links were encountered in translating the
1637pathname
1638
1639@item EISDIR
1640The named file is a directory.
1641
1642@item EROFS
1643The named file resides on a read-only file system
1644
1645@item ETXTBSY
1646The file is a pure procedure (shared text) file that is being
1647executed
1648
1649@item EIO
1650An I/O error occurred updating the inode.
1651
1652@item EFAULT
1653@code{Path} points outside the process's allocated address space.
1654
1655@item EBADF
1656The @code{fd} is not a valid descriptor.
1657
1658@end table
1659
1660@subheading DESCRIPTION:
1661
1662@code{truncate()} causes the file named by @code{path} or referenced by
1663@code{fd} to be truncated to at most @code{length} bytes in size.  If the 
1664file previously was larger than this size, the extra data is lost.  With
1665@code{ftruncate()}, the file must be open for writing.
1666
1667@subheading NOTES:
1668
1669NONE
1670
1671@page
1672@subsection pathconf - Gets configuration values for files
1673
1674@subheading CALLING SEQUENCE:
1675
1676@ifset is-C
1677@example
1678#include <unistd.h>
1679
1680int pathconf(
1681  const char *path,
1682  int         name
1683);
1684@end example
1685@end ifset
1686
1687@ifset is-Ada
1688@end ifset
1689
1690@subheading STATUS CODES:
1691
1692@table @b
1693@item EINVAL
1694Invalid argument
1695
1696@item EACCES
1697Permission to write the file is denied
1698
1699@item ENAMETOOLONG
1700Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC
1701is in effect.
1702
1703@item ENOENT
1704A file or directory does not exist
1705
1706@item ENOTDIR
1707A component of the specified @code{path} was not a directory whan a
1708directory was expected.
1709
1710@end table
1711
1712@subheading DESCRIPTION:
1713
1714@code{pathconf()} gets a value for the configuration option @code{name}
1715for the open file descriptor @code{filedes}.
1716
1717The possible values for @code{name} are:
1718
1719@table @b
1720@item _PC_LINK_MAX
1721returns the maximum number of links to the file.  If @code{filedes} or
1722@code{path} refer to a directory, then the value applies to the whole
1723directory.  The corresponding macro is @code{_POSIX_LINK_MAX}.
1724
1725@item _PC_MAX_CANON
1726returns  the maximum length of a formatted input line, where @code{filedes}
1727or @code{path} must refer to a terminal.  The corresponding macro is
1728@code{_POSIX_MAX_CANON}.
1729
1730@item _PC_MAX_INPUT
1731returns the maximum length of an input line, where @code{filedes} or
1732@code{path} must refer to a terminal.  The corresponding macro is
1733@code{_POSIX_MAX_INPUT}.
1734
1735@item _PC_NAME_MAX
1736returns the maximum length of a filename in the directory @code{path} or
1737@code{filedes}.  The process is allowed to create. The corresponding macro
1738is @code{_POSIX_NAME_MAX}.
1739
1740@item _PC_PATH_MAX
1741returns the maximum length of a relative pathname when @code{path} or
1742@code{filedes} is the current working directory.  The corresponding macro
1743is @code{_POSIX_PATH_MAX}.
1744
1745@item _PC_PIPE_BUF
1746returns the size of the pipe buffer, where @code{filedes} must refer to a
1747pipe or FIFO and @code{path} must refer to a FIFO.  The corresponding macro
1748is @code{_POSIX_PIPE_BUF}.
1749
1750@item _PC_CHOWN_RESTRICTED
1751returns nonzero if the chown(2) call may not be used on this file.  If
1752@code{filedes} or @code{path} refer to a directory, then this applies to all
1753files in that directory.  The corresponding macro is
1754@code{_POSIX_CHOWN_RESTRICTED}.
1755
1756@end table
1757
1758@subheading NOTES:
1759
1760Files with name lengths longer than the value returned for @code{name} equal
1761@code{_PC_NAME_MAX} may exist in the given directory.
1762
1763@page
1764@subsection fpathconf - Gets configuration values for files
1765
1766@subheading CALLING SEQUENCE:
1767
1768@ifset is-C
1769@example
1770#include <unistd.h>
1771
1772int fpathconf(
1773  int filedes,
1774  int name
1775);
1776@end example
1777@end ifset
1778
1779@ifset is-Ada
1780@end ifset
1781
1782@subheading STATUS CODES:
1783
1784@table @b
1785@item EINVAL
1786Invalid argument
1787
1788@item EACCES
1789Permission to write the file is denied
1790@item ENAMETOOLONG
1791
1792Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC
1793is in effect.
1794
1795@item ENOENT
1796A file or directory does not exist
1797
1798@item ENOTDIR
1799A component of the specified @code{path} was not a directory whan a
1800directory was expected.
1801
1802@end table
1803
1804
1805@subheading DESCRIPTION:
1806
1807@code{pathconf()} gets a value for the configuration option @code{name}
1808for the open file descriptor @code{filedes}.
1809
1810The possible values for name are:
1811
1812@table @b
1813@item _PC_LINK_MAX
1814returns the maximum number of links to the file.  If @code{filedes} or
1815@code{path} refer to a directory, then the value applies to the whole
1816directory.  The corresponding macro is _POSIX_LINK_MAX.
1817
1818@item _PC_MAX_CANON
1819returns  the maximum length of a formatted input line, where @code{filedes}
1820or @code{path} must refer to a terminal.  The corresponding macro is
1821@code{_POSIX_MAX_CANON}.
1822
1823@item _PC_MAX_INPUT
1824returns the maximum length of an input line, where @code{filedes} or
1825@code{path} must refer to a terminal.  The corresponding macro is
1826@code{_POSIX_MAX_INPUT}.
1827
1828@item _PC_NAME_MAX
1829returns the maximum length of a filename in the directory @code{path} or
1830@code{filedes}.  The process is allowed to create. The corresponding macro
1831is @code{_POSIX_NAME_MAX}.
1832
1833@item _PC_PATH_MAX
1834returns the maximum length of a relative pathname when @code{path} or
1835@code{filedes} is the current working directory.  The corresponding macro
1836is @code{_POSIX_PATH_MAX}.
1837
1838@item _PC_PIPE_BUF
1839returns the size of the pipe buffer, where @code{filedes} must refer to a
1840pipe or FIFO and @code{path} must refer to a FIFO.  The corresponding macro
1841is @code{_POSIX_PIPE_BUF}.
1842
1843@item _PC_CHOWN_RESTRICTED
1844returns nonzero if the @code{chown()} call may not be used on this file.  If
1845@code{filedes} or @code{path} refer to a directory, then this applies to all
1846files in that directory.  The corresponding macro is
1847@code{_POSIX_CHOWN_RESTRICTED}.
1848
1849@end table
1850
1851@subheading NOTES:
1852
1853NONE
1854
1855@page
1856@subsection mknod - create a directory
1857
1858@subheading CALLING SEQUENCE:
1859
1860@ifset is-C
1861@example
1862#include <unistd.h>
1863#include <fcntl.h>
1864#include <sys/types.h>
1865#include <sys/stat.h>
1866
1867long mknod(
1868  const char *pathname,
1869  mode_t      mode,
1870  dev_t       dev
1871);
1872@end example
1873@end ifset
1874
1875@ifset is-Ada
1876@end ifset
1877
1878@subheading STATUS CODES:
1879
1880@code{mknod} returns zero on success, or -1 if an error occurred (in which case,
1881errno is set appropriately).
1882
1883@table @b
1884@item ENAMETOOLONG
1885@code{pathname} was too long.
1886
1887@item ENOENT
1888A directory component in @code{pathname} does not exist or is a dangling symbolic
1889link.
1890
1891@item ENOTDIR
1892A component used in the directory @code{pathname} is not, in fact, a directory.
1893
1894@item ENOMEM
1895Insufficient kernel memory was available
1896
1897@item EROFS
1898@code{pathname} refers to a file on a read-only filesystem.
1899
1900@item ELOOP
1901@code{pathname} contains a reference to a circular symbolic link, ie a symbolic
1902link whose expansion contains a reference to itself.
1903
1904@item ENOSPC
1905The device containing @code{pathname} has no room for the new node.
1906
1907@end table
1908
1909@subheading DESCRIPTION:
1910
1911@code{mknod} attempts to create a filesystem node (file, device special file or
1912named pipe) named @code{pathname}, specified by @code{mode} and @code{dev}.
1913
1914@code{mode} specifies both the permissions to use and the type of node to be created.
1915
1916It should be a combination (using bitwise OR) of one of the file types listed
1917below and the permissions for the new node.
1918
1919The permissions are modified by the process's @code{umask} in the usual way: the
1920permissions of the created node are @code{(mode & ~umask)}.
1921
1922The file type should be one of @code{S_IFREG}, @code{S_IFCHR}, @code{S_IFBLK} and
1923@code{S_IFIFO} to specify a normal file (which will be created empty), character
1924special file, block special file or FIFO (named pipe), respectively, or zero, which
1925will create a normal file.
1926
1927If the file type is @code{S_IFCHR} or @code{S_IFBLK} then @code{dev} specifies the major 
1928and minor numbers of the newly created device special file; otherwise it is ignored.
1929
1930The newly created node will be owned by the effective uid of the process.  If the
1931directory containing the node has the set group id bit set, or if the filesystem
1932is mounted with BSD group semantics, the new node will inherit the group ownership
1933from its parent directory; otherwise it will be owned by the effective gid of the
1934process.
1935
1936
1937@subheading NOTES:
1938
1939NONE
Note: See TracBrowser for help on using the repository browser.