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

4.104.114.84.9
Last change on this file since 9a0b008 was 9a0b008, checked in by Wade A Smith <warm38@…>, on Sep 25, 1998 at 4:20:52 PM

Docmumented the access routine in for this file.

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