source: rtems/doc/new_chapters/files.t @ 64183e20

4.104.114.84.9
Last change on this file since 64183e20 was 64183e20, checked in by Wade A Smith <warm38@…>, on Sep 25, 1998 at 8:11:51 PM

Documented the creat, scandir, and access routines.

  • Property mode set to 100644
File size: 27.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{readdir_r} -
21@item @code{rewinddir} -
22@item @code{scandir} - Scan a directory for matching entries
23@item @code{telldir} -
24@item @code{closedir} -
25@item @code{getdents}
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} -
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} -
39@item @code{access} - Check user's permissions for a file.
40@item @code{chmod} - Changes file mode
41@item @code{fchmod} -
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} -
46@item @code{fpathconf} -
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 -
181
182@subheading CALLING SEQUENCE:
183
184@ifset is-C
185@example
186int rewinddir(
187);
188@end example
189@end ifset
190
191@ifset is-Ada
192@end ifset
193
194@subheading STATUS CODES:
195
196@table @b
197@item E
198The
199
200@end table
201
202@subheading DESCRIPTION:
203
204@subheading NOTES:
205
206The routine is implemented in Cygnus newlib.
207
208@page
209@subsection scandir - Scan a directory for matching entries
210
211@subheading CALLING SEQUENCE:
212
213@ifset is-C
214@example
215#include <dirent.h>
216
217int scandir(const char      *dir,
218            struct direct ***namelist,
219            int (*select)(const struct dirent *),
220            int (*compar)(const struct dirent **, const struct dirent **)
221);
222@end example
223@end ifset
224
225@ifset is-Ada
226@end ifset
227
228@subheading STATUS CODES:
229
230@table @b
231@item ENOMEM
232Insufficient memory to complete the operation.
233
234@end table
235
236@subheading DESCRIPTION:
237
238The @code{scandir()} function scans the directory @code{dir}, calling
239@code{select()} on each directory entry.  Entries for which @code{select()}
240returns non-zero are stored in strings allocated via @code{malloc()},
241sorted using @code{qsort()} with the comparison function @code{compar()},
242and collected in array @code{namelist} which is allocated via @code{malloc()}.
243If @code{select} is NULL, all entries are selected.
244
245@subheading NOTES:
246
247The routine is implemented in Cygnus newlib.
248
249@page
250@subsection telldir -
251
252@subheading CALLING SEQUENCE:
253
254@ifset is-C
255@example
256int telldir(
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 E
268The
269
270@end table
271
272@subheading DESCRIPTION:
273
274@subheading NOTES:
275
276The routine is implemented in Cygnus newlib.
277
278
279@page
280@subsection closedir -
281
282@subheading CALLING SEQUENCE:
283
284@ifset is-C
285@example
286int closedir(
287);
288@end example
289@end ifset
290
291@ifset is-Ada
292@end ifset
293
294@subheading STATUS CODES:
295
296@table @b
297@item E
298The
299
300@end table
301
302@subheading DESCRIPTION:
303
304@subheading NOTES:
305
306The routine is implemented in Cygnus newlib.
307
308@page
309@subsection chdir - Changes the current working directory
310
311@subheading CALLING SEQUENCE:
312
313@ifset is-C
314@example
315#include <unistd.h>
316
317int chdir( const char  *path
318);
319@end example
320@end ifset
321
322@ifset is-Ada
323@end ifset
324
325@subheading STATUS CODES:
326
327@table @b
328@item EACCES
329Search permission is denied for a directory in a file's path prefix.
330
331@item ENAMETOOLONG
332Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
333in effect.
334
335@item ENOENT
336A file or directory does not exist.
337
338@item ENOTDIR
339A component of the specified pathname was not a directory when directory
340was expected.
341
342@end table
343
344@subheading DESCRIPTION:
345
346The @code{chdir()} function causes the directory named by @code{path} to
347become the current working directory; that is, the starting point for
348searches of pathnames not beginning with a slash.
349
350If @code{chdir()} detects an error, the current working directory is not
351changed.
352
353@subheading NOTES: None
354
355@page
356@subsection getcwd - Gets current working directory
357
358@subheading CALLING SEQUENCE:
359
360@ifset is-C
361@example
362#include <unistd.h>
363
364int getcwd(
365);
366@end example
367@end ifset
368
369@ifset is-Ada
370@end ifset
371
372@subheading STATUS CODES:
373
374@table @b
375@item EINVAL
376Invalid argument
377
378@item ERANGE
379Result is too large
380
381@item EACCES
382Search permission is denied for a directory in a file's path prefix.
383
384@end table
385
386@subheading DESCRIPTION:
387
388The @code{getcwd()} function copies the absolute pathname of the current
389working directory to the character array pointed to by @code{buf}.  The
390@code{size} argument is the number of bytes available in @code{buf}
391
392@subheading NOTES:
393
394There is no way to determine the maximum string length that @code{fetcwd()}
395may need to return.  Applications should tolerate getting @code{ERANGE}
396and allocate a larger buffer.
397
398It is possible for @code{getcwd()} to return EACCES if, say, @code{login}
399puts the process into a directory without read access.
400
401The 1988 standard uses @code{int} instead of @code{size_t} for the second
402parameter.
403
404@page
405@subsection open - Opens a file
406
407@subheading CALLING SEQUENCE:
408
409@ifset is-C
410@example
411#include <sys/types.h>
412#include <sys/stat.h>
413#include <fcntl.h>
414
415int open(
416   const char *path,
417   int         oflag,
418   mode_t      mode
419);
420@end example
421@end ifset
422
423@ifset is-Ada
424@end ifset
425
426@subheading STATUS CODES:
427
428@table @b
429@item EACCES
430Search permission is denied for a directory in a file's path prefix.
431@item EEXIST
432The named file already exists.
433@item EINTR
434Function was interrupted by a signal.
435@item EISDIR
436Attempt to open a directory for writing or to rename a file to be a
437directory.
438@item EMFILE
439Too many file descriptors are in use by this process.
440@item ENAMETOOLONG
441Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
442effect.
443@item ENFILE
444Too many files are currently open in the system.
445@item ENOENT
446A file or directory does not exist.
447@item ENOSPC
448No space left on disk.
449@item ENOTDIR
450A component of the specified pathname was not a directory when a directory
451was expected.
452@item ENXIO
453No such device.  This error may also occur when a device is not ready, for
454example, a tape drive is off-line.
455@item EROFS
456Read-only file system.
457@end table
458
459@subheading DESCRIPTION:
460
461The @code{open} function establishes a connection between a file and a file
462descriptor.  The file descriptor is a small integer that is used by I/O
463functions to reference the file.  The @code{path} argument points to the
464pathname for the file.
465
466The @code{oflag} argument is the bitwise inclusive OR of the values of
467symbolic constants.  The programmer must specify exactly one of the following
468three symbols:
469
470@table @b
471@item O_RDONLY
472Open for reading only.
473
474@item O_WRONLY
475Open for writing only.
476
477@item O_RDWR
478Open for reading and writing.
479
480@end table
481
482Any combination of the following symbols may also be used.
483
484@table @b
485@item O_APPEND
486Set the file offset to the end-of-file prior to each write.
487
488@item O_CREAT
489If the file does not exist, allow it to be created.  This flag indicates
490that the @code{mode} argument is present in the call to @code{open}.
491
492@item O_EXCL
493This flag may be used only if O_CREAT is also set.  It causes the call
494to @code{open} to fail if the file already exists.
495
496@item O_NOCTTY
497If @code{path} identifies a terminal, this flag prevents that teminal from
498becoming the controlling terminal for thi9s process.  See Chapter 8 for a
499description of terminal I/O.
500
501@item O_NONBLOCK
502Do no wait for the device or file to be ready or available.  After the file
503is open, the @code{read} and @code{write} calls return immediately.  If the
504process would be delayed in the read or write opermation, -1 is returned and
505@code{errno} is set to @code{EAGAIN} instead of blocking the caller.
506
507@item O_TRUNC
508This flag should be used only on ordinary files opened for writing.  It
509causes the file to be tuncated to zero length..
510
511@end table
512
513Upon successful completion, @code{open} returns a non-negative file
514descriptor.
515
516@subheading NOTES:
517
518
519@page
520@subsection creat - Create a new file or rewrite an existing one
521
522@subheading CALLING SEQUENCE:
523
524@ifset is-C
525@example
526#include <sys/types.h>
527#include <sys/stat.h>
528#include <fcntl.h>
529
530int creat(const char *path,
531          mode_t      mode
532);
533@end example
534@end ifset
535
536@ifset is-Ada
537@end ifset
538
539@subheading STATUS CODES:
540
541@table @b
542@item EEXIST
543@code{Path} already exists and O_CREAT and O_EXCL were used.
544@item EISDIR
545@code{Path} refers to a directory and the access requested involved
546writing
547@item ETXTBSY
548@code{Path} refers to an executable image which is currently being
549executed and write access was requested
550@item EFAULT
551@code{Path} points outside your accessible address space
552@item EACCES
553The requested access to the file is not allowed, or one of the
554directories in @code{path} did not allow search (execute) permission.
555@item ENAMETOOLONG
556@code{Path} was too long.
557@item ENOENT
558A directory component in @code{path} does not exist or is a dangling
559symbolic link.
560@item ENOTDIR
561A component used as a directory in @code{path} is not, in fact, a
562directory.
563@item EMFILE
564The process alreadyh has the maximum number of files open.
565@item ENFILE
566The limit on the total number of files open on the system has been
567reached.
568@item ENOMEM
569Insufficient kernel memory was available.
570@item EROFS
571@code{Path} refers to a file on a read-only filesystem and write access
572was requested
573
574@end table
575
576@subheading DESCRIPTION:
577
578@code{creat} attempts to create a file and return a file descriptor for
579use in read, write, etc.
580
581@subheading NOTES: None
582
583The routine is implemented in Cygnus newlib.
584
585@page
586@subsection umask - Sets a file creation mask.
587
588@subheading CALLING SEQUENCE:
589
590@ifset is-C
591@example
592#include <sys/types.h>
593#include <sys/stat.h>
594
595mode_t umask(
596  mode_t cmask
597);
598@end example
599@end ifset
600
601@ifset is-Ada
602@end ifset
603
604@subheading STATUS CODES:
605
606@subheading DESCRIPTION:
607
608The @code{umask()} function sets the process file creation mask to @code{cmask}.
609The file creation mask is used during @code{open()}, @code{creat()}, @code{mkdir()},
610@code{mkfifo()} calls to turn off permission bits in the @code{mode} argument.
611Bit positions that are set in @code{cmask} are cleared in the mode of the
612created file.
613
614@subheading NOTES: None
615
616The @code{cmask} argument should have only permission bits set.  All other
617bits should be zero.
618
619In a system which supports multiple processes, the file creation mask is inherited
620across @code{fork()} and @code{exec()} calls.  This makes it possible to alter the
621default permission bits of created files.  RTEMS does not support multiple processes
622so this behavior is not possible.
623
624@page
625@subsection link - Creates a link to a file
626
627@subheading CALLING SEQUENCE:
628
629@ifset is-C
630@example
631#include <unistd.h>
632
633int link(
634  const char *existing,
635  const char *new
636);
637@end example
638@end ifset
639
640@ifset is-Ada
641@end ifset
642
643@subheading STATUS CODES:
644
645@table @b
646@item EACCES
647Search permission is denied for a directory in a file's path prefix
648@item EEXIST
649The named file already exists.
650@item EMLINK
651The number of links would exceed @code{LINK_MAX}.
652@item ENAMETOOLONG
653Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
654effect.
655@item ENOENT
656A file or directory does not exist.
657@item ENOSPC
658No space left on disk.
659@item ENOTDIR
660A component of the specified pathname was not a directory when a directory
661was expected.
662@item EPERM
663Operation is not permitted.  Process does not have the appropriate priviledges
664or permissions to perform the requested operations.
665@item EROFS
666Read-only file system.
667@item EXDEV
668Attempt to link a file to another file system.
669
670@end table
671
672@subheading DESCRIPTION:
673
674The @code{link} function atomically creates a new link for an existing file
675and increments the link count for the file.
676
677If the @code{link} function fails, no directories are modified.
678
679The @code{existing} argument should not be a directory.
680
681The callder may (or may not) need permission to access the existing file.
682
683@subheading NOTES: None
684
685@page
686@subsection mkdir - Makes a directory
687
688@subheading CALLING SEQUENCE:
689
690@ifset is-C
691@example
692#include <sys/types.h>
693#include <sys/stat.h>
694
695int mkdir(
696  const char *path,
697  mode_t      mode
698);
699@end example
700@end ifset
701
702@ifset is-Ada
703@end ifset
704
705@subheading STATUS CODES:
706
707@table @b
708@item EACCES
709Search permission is denied for a directory in a file's path prefix
710@item EEXIST
711The name file already exist. 
712@item EMLINK
713The number of links would exceed LINK_MAX
714@item ENAMETOOLONG
715Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
716effect.
717@item ENOENT
718A file or directory does not exist.
719@item ENOSPC
720No space left on disk.
721@item ENOTDIR
722A component of the specified pathname was not a directory when a directory
723was expected.
724@item EROFS
725Read-only file system.
726
727@end table
728
729@subheading DESCRIPTION:
730
731The @code{mkdir()} function creates a new diectory named @code{path}.  The
732permission bits (modified by the file creation mask) are set from @code{mode}.
733The owner and group IDs for the directory are set from the effective user ID
734and group ID.
735
736The new directory may (or may not) contain entries for.. and .. but is otherwise
737empty.
738
739@subheading NOTES: None
740
741@page
742@subsection mkfifo -
743
744@subheading CALLING SEQUENCE:
745
746@ifset is-C
747@example
748int mkfifo(
749);
750@end example
751@end ifset
752
753@ifset is-Ada
754@end ifset
755
756@subheading STATUS CODES:
757
758@table @b
759@item E
760The
761
762@end table
763
764@subheading DESCRIPTION:
765
766@subheading NOTES:
767
768@page
769@subsection unlink - Removes a directory entry
770
771@subheading CALLING SEQUENCE:
772
773@ifset is-C
774@example
775#include <unistd.h>
776
777int unlink(
778  const char path
779);
780@end example
781@end ifset
782
783@ifset is-Ada
784@end ifset
785
786@subheading STATUS CODES:
787
788@table @b
789@item EACCES
790Search permission is denied for a directory in a file's path prefix
791@item EBUSY
792The directory is in use.
793@item ENAMETOOLONG
794Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
795effect.
796@item ENOENT
797A file or directory does not exist.
798@item ENOTDIR
799A component of the specified pathname was not a directory when a directory
800was expected.
801@item EPERM
802Operation is not permitted.  Process does not have the appropriate priviledges
803or permissions to perform the requested operations.
804@item EROFS
805Read-only file system.
806
807@end table
808
809@subheading DESCRIPTION:
810
811The @code{unlink} function removes the link named by @code{path} and decrements the
812link count of the file referenced by the link.  When the link count goes to zero
813and no process has the file open, the space occupied by the file is freed and the
814file is no longer accessible.
815
816@subheading NOTES: None
817
818@page
819@subsection rmdir - Delete a directory
820
821@subheading CALLING SEQUENCE:
822
823@ifset is-C
824@example
825#include <unistd.h>
826
827int rmdir(const char *pathname
828);
829@end example
830@end ifset
831
832@ifset is-Ada
833@end ifset
834
835@subheading STATUS CODES:
836
837@table @b
838@item EPERM
839The filesystem containing @code{pathname} does not support the removal
840of directories.
841@item EFAULT
842@cdoe{Pathname} points ouside your accessible address space.
843@item EACCES
844Write access to the directory containing @code{pathname} was not
845allowed for the process's effective uid, or one of the directories in
846@code{pathname} did not allow search (execute) permission.
847@item EPERM
848The directory containing @code{pathname} has the stickybit (S_ISVTX)
849set and the process's effective uid is neither the uid of the file to
850be delected nor that of the director containing it.
851@item ENAMETOOLONG
852@code{Pathname} was too long.
853@item ENOENT
854A dirctory component in @code{pathname} does not exist or is a
855dangling sybolic link.
856@item ENOTDIR
857@code{Pathname}, or a component used as a directory in @code{pathname},
858is not, in fact, a directory.
859@item ENOTEMPTY
860@code{Pathname} contains entries other than . and .. .
861@item EBUSY
862@code{Pathname} is the current working directory or root directory of
863some process
864@item EBUSY
865@code{Pathname} is the current directory or root directory of some
866process.
867@item ENOMEM
868Insufficient kernel memory was available
869@item EROGS
870@code{Pathname} refers to a file on a read-only filesystem.
871@itemELOOP
872@code{Pathname} contains a reference to a circular symbolic link
873
874@end table
875
876@subheading DESCRIPTION:
877
878@code{rmdir} deletes a directory, whic must be empty
879
880
881@subheading NOTES: None
882
883@page
884@subsection rename - Renames a file
885
886@subheading CALLING SEQUENCE:
887
888@ifset is-C
889@example
890#include <unistd.h>
891
892int rename(const char *old,
893           const char *new
894);
895@end example
896@end ifset
897
898@ifset is-Ada
899@end ifset
900
901@subheading STATUS CODES:
902
903@table @b
904@item EACCES
905Search permission is denied for a directory in a file's path prefix.
906@item EBUSY
907The directory is in use.
908@item EEXIST
909The named file already exists.
910@item EINVAL
911Invalid argument.
912@item EISDIR
913Attempt to open a directory for writing or to rename a file to be a
914directory.
915@item EMLINK
916The number of links would exceed LINK_MAX.
917@item ENAMETOOLONG
918Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
919in effect.
920@item ENOENT
921A file or directory does no exist.
922@item ENOSPC
923No space left on disk.
924@item ENOTDIR
925A component of the specified pathname was not a directory when a
926directory was expected.
927@item ENOTEMPTY
928Attempt to delete or rename a non-empty directory.
929@item EROFS
930Read-only file system
931@item EXDEV
932Attempt to link a file to another file system.
933@end table
934
935@subheading DESCRIPTION:
936
937The @code{rename()} function causes the file known bo @code{old} to
938now be known as @code{new}.
939
940Ordinary files may be renamed to ordinary files, and directories may be
941renamed to directories; however, files cannot be converted using
942@code{rename()}.  The @code{new} pathname may not contain a path prefix
943of @code{old}.
944
945@subheading NOTES:
946
947If a file already exists by the name @code{new}, it is removed.  The
948@code{rename()} function is atomic.  If the @code{rename()} detects an
949error, no files are removed.  This guarantees that the
950@code{rename("x", "x")} does not remove @code{x}.
951
952You may not rename dot or dot-dot.
953
954The routine is implemented in Cygnus newlib using @code{link()} and
955@code{unlink()}.
956
957@page
958@subsection stat - Gets information about a file
959
960@subheading CALLING SEQUENCE:
961
962@ifset is-C
963@example
964#include <sys/types.h>
965#include <sys/stat.h>
966
967int stat(const char  *path,
968         struct stat *buf
969);
970@end example
971@end ifset
972
973@ifset is-Ada
974@end ifset
975
976@subheading STATUS CODES:
977
978@table @b
979@item EACCES
980Search permission is denied for a directory in a file's path prefix.
981@item EBADF
982Invalid file descriptor.
983@item ENAMETOOLONG
984Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
985in effect.
986@item ENOENT
987A file or directory does not exist.
988@item ENOTDIR
989A component of the specified pathname was not a directory when a
990directory was expected.
991
992@end table
993
994@subheading DESCRIPTION:
995
996The @code{path} argument points to a pathname for a file.  Read, write, or
997execute permission for the file is not required, but all directories listed
998in @code{path} must be searchable.  The @code{stat()} function obtains
999information about the named file and writes it to the area pointed to by
1000@code{but}.
1001
1002@subheading NOTES: None
1003
1004@page
1005@subsection fstat -
1006
1007@subheading CALLING SEQUENCE:
1008
1009@ifset is-C
1010@example
1011int fstat(
1012);
1013@end example
1014@end ifset
1015
1016@ifset is-Ada
1017@end ifset
1018
1019@subheading STATUS CODES:
1020
1021@table @b
1022@item E
1023The
1024
1025@end table
1026
1027@subheading DESCRIPTION:
1028
1029@subheading NOTES:
1030
1031@page
1032@subsection access - Check user's permissions for a file
1033
1034@subheading CALLING SEQUENCE:
1035
1036@ifset is-C
1037@example
1038#include <unistd.h>
1039
1040int access(const char *pathname,
1041           int         mode
1042);
1043@end example
1044@end ifset
1045
1046@ifset is-Ada
1047@end ifset
1048
1049@subheading STATUS CODES:
1050
1051@table @b
1052@item EACCES
1053The requested access would be denied, either to the file itself or
1054one of the directories in @code{pathname}.
1055@item EFAULT
1056@code{Pathname} points outside your accessible address space.
1057@item EINVAL
1058@code{Mode} was incorrectly specified.
1059@item ENAMETOOLONG
1060@code{Pathname} is too long.
1061@item ENOENT
1062A directory component in @code{pathname} would have been accessible but
1063does not exist or was a dangling symbolic link.
1064@item ENOTDIR
1065A component used as a directory in @code{pathname} is not, in fact,
1066a directory.
1067@item ENOMEM
1068Insufficient kernel memory was available.
1069
1070@end table
1071
1072@subheading DESCRIPTION:
1073
1074@code{Access} checks whether the process would be allowed to read, write or
1075test for existence of the file (or other file system object) whose name is
1076@code{pathname}.  If @code{pathname} is a symbolic link permissions of the
1077file referred by this symbolic link are tested.
1078
1079@code{Mode} is a mask consisting of one or more of R_OK, W_OK, X_OK and F_OK.
1080
1081@subheading NOTES: None
1082
1083@page
1084@subsection chmod - Changes file mode.
1085
1086@subheading CALLING SEQUENCE:
1087
1088@ifset is-C
1089@example
1090#include <sys/types.h>
1091#include <sys/stat.h>
1092
1093int chmod(
1094  const char *path,
1095  mode_t      mode
1096);
1097@end example
1098@end ifset
1099
1100@ifset is-Ada
1101@end ifset
1102
1103@subheading STATUS CODES:
1104
1105@table @b
1106@item EACCES
1107Search permission is denied for a directory in a file's path prefix
1108@item ENAMETOOLONG
1109Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
1110effect.
1111@item ENOENT
1112A file or directory does not exist.
1113@item ENOTDIR
1114A component of the specified pathname was not a directory when a directory
1115was expected.
1116@item EPERM
1117Operation is not permitted.  Process does not have the appropriate priviledges
1118or permissions to perform the requested operations.
1119@item EROFS
1120Read-only file system.
1121
1122@end table
1123
1124@subheading DESCRIPTION:
1125
1126Set the file permission bits, the set user ID bit, and the set group ID bit
1127for the file named by @code{path} to @code{mode}.  If the effective user ID
1128does not match the owner of the file and the calling process does not have
1129the appropriate privileges, @code{chmod()} returns -1 and sets @code{errno} to
1130@code{EPERM}.
1131
1132@subheading NOTES:
1133
1134@page
1135@subsection fchmod -
1136
1137@subheading CALLING SEQUENCE:
1138
1139@ifset is-C
1140@example
1141int fchmod(
1142);
1143@end example
1144@end ifset
1145
1146@ifset is-Ada
1147@end ifset
1148
1149@subheading STATUS CODES:
1150
1151@table @b
1152@item E
1153The
1154
1155@end table
1156
1157@subheading DESCRIPTION:
1158
1159@subheading NOTES:
1160
1161@page
1162@subsection chown - Changes the owner and/or group of a file.
1163
1164@subheading CALLING SEQUENCE:
1165
1166@ifset is-C
1167@example
1168#include <sys/types.h>
1169#include <unistd.h>
1170
1171int chown(
1172  const char *path,
1173  uid_t       owner,
1174  gid_t       group
1175);
1176@end example
1177@end ifset
1178
1179@ifset is-Ada
1180@end ifset
1181
1182@subheading STATUS CODES:
1183
1184@table @b
1185@item EACCES
1186Search permission is denied for a directory in a file's path prefix
1187@item EINVAL
1188Invalid argument
1189@item ENAMETOOLONG
1190Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
1191effect.
1192@item ENOENT
1193A file or directory does not exist.
1194@item ENOTDIR
1195A component of the specified pathname was not a directory when a directory
1196was expected.
1197@item EPERM
1198Operation is not permitted.  Process does not have the appropriate priviledges
1199or permissions to perform the requested operations.
1200@item EROFS
1201Read-only file system.
1202
1203@end table
1204
1205@subheading DESCRIPTION:
1206
1207The user ID and group ID of the file named by @code{path} are set to
1208@code{owner} and @code{path}, respectively.
1209
1210For regular files, the set group ID (S_ISGID) and set user ID (S_ISUID)
1211bits are cleared.
1212
1213Some systems consider it a security violation to allow the owner of a file to
1214be changed,  If users are billed for disk space usage, loaning a file to
1215another user could result in incorrect billing.  The @code{chown()} function
1216may be restricted to privileged users for some or all files.  The group ID can
1217still be changed to one of the supplementary group IDs.
1218
1219@subheading NOTES:
1220
1221This function may be restricted for some file.  The @code{pathconf} function
1222can be used to test the _PC_CHOWN_RESTRICTED flag.
1223
1224
1225
1226@page
1227@subsection utime - Change access and/or modification times of an inode
1228
1229@subheading CALLING SEQUENCE:
1230
1231@ifset is-C
1232@example
1233#include <sys/types.h>
1234
1235int utime(const char     *filename,
1236          struct utimbuf *buf
1237);
1238@end example
1239@end ifset
1240
1241@ifset is-Ada
1242@end ifset
1243
1244@subheading STATUS CODES:
1245
1246@table @b
1247@item EACCES
1248Permission to write the file is denied
1249@item ENOENT
1250@code{Filename} does not exist
1251
1252@end table
1253
1254@subheading DESCRIPTION:
1255
1256@code{Utime} changes the access and modification times of the inode
1257specified by @code{filename} to the @code{actime} and @code{modtime}
1258fields of @code{buf} respectively.  If @code{buf} is NULL, then the
1259access and modification times of the file are set to the current time. 
1260
1261@subheading NOTES:
1262
1263@page
1264@subsection ftrunctate -
1265
1266@subheading CALLING SEQUENCE:
1267
1268@ifset is-C
1269@example
1270int ftrunctate(
1271);
1272@end example
1273@end ifset
1274
1275@ifset is-Ada
1276@end ifset
1277
1278@subheading STATUS CODES:
1279
1280@table @b
1281@item E
1282The
1283
1284@end table
1285
1286@subheading DESCRIPTION:
1287
1288@subheading NOTES:
1289
1290@page
1291@subsection pathconf -
1292
1293@subheading CALLING SEQUENCE:
1294
1295@ifset is-C
1296@example
1297int pathconf(
1298);
1299@end example
1300@end ifset
1301
1302@ifset is-Ada
1303@end ifset
1304
1305@subheading STATUS CODES:
1306
1307@table @b
1308@item E
1309The
1310
1311@end table
1312
1313@subheading DESCRIPTION:
1314
1315@subheading NOTES:
1316
1317@page
1318@subsection fpathconf -
1319
1320@subheading CALLING SEQUENCE:
1321
1322@ifset is-C
1323@example
1324int fpathconf(
1325);
1326@end example
1327@end ifset
1328
1329@ifset is-Ada
1330@end ifset
1331
1332@subheading STATUS CODES:
1333
1334@table @b
1335@item E
1336The
1337
1338@end table
1339
1340@subheading DESCRIPTION:
1341
1342@subheading NOTES:
1343
Note: See TracBrowser for help on using the repository browser.