source: rtems/doc/new_chapters/files.t @ 487c5d58

4.104.114.84.9
Last change on this file since 487c5d58 was 487c5d58, checked in by Wade A Smith <warm38@…>, on Sep 28, 1998 at 10:08:41 PM

Documented the ftruncate and opendir routines. Removed reference to the
readdir_r routine.

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