source: rtems/doc/new_chapters/files.t @ e21f7d8

4.104.114.84.95
Last change on this file since e21f7d8 was 389c3e9, checked in by Wade A Smith <warm38@…>, on 09/26/98 at 19:33:58

Documented the following routines in this file: rewinddir, pathconf,
fpathconf, fchmod, fstat, mkfifo, and telldir

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