Changeset 1d2366e in rtems


Ignore:
Timestamp:
Sep 25, 1998, 12:50:36 PM (21 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, master
Children:
97149ba
Parents:
7a86dc4
Message:

Stuff added by Kerwin.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/new_chapters/files.t

    r7a86dc4 r1d2366e  
    1111@section Introduction
    1212
    13 The
    14 files and directories manager is ...
     13The files and directories manager is ...
    1514
    1615The directives provided by the files and directories manager are:
    1716
    1817@itemize @bullet
    19 @item @code{opendir} -
    20 @item @code{readdir} -
     18@item @code{opendir} - Open a Directory
     19@item @code{readdir} - Reads a directory
    2120@item @code{readdir_r} -
    2221@item @code{rewinddir} -
     22@item @code{scandir} -
     23@item @code{telldir} -
    2324@item @code{closedir} -
    24 @item @code{chdir} -
    25 @item @code{getcwd} -
    26 @item @code{open} -
     25@item @code{chdir} - Changes the current working directory
     26@item @code{getcwd} - Gets current working directory
     27@item @code{open} - Opens a file
    2728@item @code{creat} -
    28 @item @code{umask} -
    29 @item @code{link} -
    30 @item @code{mkdir} -
     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
    3132@item @code{mkfifo} -
    32 @item @code{unlink} -
     33@item @code{unlink} - Removes a directory entry
    3334@item @code{rmdir} -
    34 @item @code{rename} -
    35 @item @code{stat} -
     35@item @code{rename} - Renames a file
     36@item @code{stat} - Gets information about a file.
    3637@item @code{fstat} -
    3738@item @code{access} -
    38 @item @code{chmod} -
     39@item @code{chmod} - Changes file mode
    3940@item @code{fchmod} -
    40 @item @code{chown} -
     41@item @code{chown} - Changes the owner and/ or group of a file
    4142@item @code{utime} -
    4243@item @code{ftrunctate} -
     
    5758
    5859@page
    59 @subsection opendir -
    60 
    61 @subheading CALLING SEQUENCE:
    62 
    63 @ifset is-C
    64 @example
     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
    6569int opendir(
    66 );
    67 @end example
    68 @end ifset
    69 
    70 @ifset is-Ada
    71 @end ifset
    72 
    73 @subheading STATUS CODES:
    74 
    75 @table @b
    76 @item E
    77 The
    78 
    79 @end table
    80 
    81 @subheading DESCRIPTION:
    82 
    83 @subheading NOTES:
    84 
    85 @page
    86 @subsection readdir -
    87 
    88 @subheading CALLING SEQUENCE:
    89 
    90 @ifset is-C
    91 @example
     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
    92111int readdir(
    93 );
    94 @end example
    95 @end ifset
    96 
    97 @ifset is-Ada
    98 @end ifset
    99 
    100 @subheading STATUS CODES:
    101 
    102 @table @b
    103 @item E
    104 The
    105 
    106 @end table
    107 
    108 @subheading DESCRIPTION:
    109 
    110 @subheading NOTES:
     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.
    111148
    112149@page
     
    137174@subheading NOTES:
    138175
     176XXX must be implemented in RTEMS.
     177
    139178@page
    140179@subsection rewinddir -
     
    164203@subheading NOTES:
    165204
     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
    166266@page
    167267@subsection closedir -
     
    191291@subheading NOTES:
    192292
    193 @page
    194 @subsection chdir -
    195 
    196 @subheading CALLING SEQUENCE:
    197 
    198 @ifset is-C
    199 @example
    200 int chdir(
    201 );
    202 @end example
    203 @end ifset
    204 
    205 @ifset is-Ada
    206 @end ifset
    207 
    208 @subheading STATUS CODES:
    209 
    210 @table @b
    211 @item E
    212 The
    213 
    214 @end table
    215 
    216 @subheading DESCRIPTION:
    217 
    218 @subheading NOTES:
    219 
    220 @page
    221 @subsection getcwd -
    222 
    223 @subheading CALLING SEQUENCE:
    224 
    225 @ifset is-C
    226 @example
     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
    227351int getcwd(
    228352);
     
    236360
    237361@table @b
    238 @item E
    239 The
    240 
    241 @end table
    242 
    243 @subheading DESCRIPTION:
    244 
    245 @subheading NOTES:
    246 
    247 @page
    248 @subsection open -
    249 
    250 @subheading CALLING SEQUENCE:
    251 
    252 @ifset is-C
    253 @example
     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 @cdoe{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
    254402int open(
    255 );
    256 @end example
    257 @end ifset
    258 
    259 @ifset is-Ada
    260 @end ifset
    261 
    262 @subheading STATUS CODES:
    263 
    264 @table @b
    265 @item E
    266 The
    267 
    268 @end table
    269 
    270 @subheading DESCRIPTION:
    271 
    272 @subheading NOTES:
     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
    273505
    274506@page
     
    299531@subheading NOTES:
    300532
    301 @page
    302 @subsection umask -
    303 
    304 @subheading CALLING SEQUENCE:
    305 
    306 @ifset is-C
    307 @example
    308 int umask(
    309 );
    310 @end example
    311 @end ifset
    312 
    313 @ifset is-Ada
    314 @end ifset
    315 
    316 @subheading STATUS CODES:
    317 
    318 @table @b
    319 @item E
    320 The
    321 
    322 @end table
    323 
    324 @subheading DESCRIPTION:
    325 
    326 @subheading NOTES:
    327 
    328 @page
    329 @subsection link -
    330 
    331 @subheading CALLING SEQUENCE:
    332 
    333 @ifset is-C
    334 @example
     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
    335583int link(
    336 );
    337 @end example
    338 @end ifset
    339 
    340 @ifset is-Ada
    341 @end ifset
    342 
    343 @subheading STATUS CODES:
    344 
    345 @table @b
    346 @item E
    347 The
    348 
    349 @end table
    350 
    351 @subheading DESCRIPTION:
    352 
    353 @subheading NOTES:
    354 
    355 @page
    356 @subsection mkdir -
    357 
    358 @subheading CALLING SEQUENCE:
    359 
    360 @ifset is-C
    361 @example
     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
    362645int mkdir(
    363 );
    364 @end example
    365 @end ifset
    366 
    367 @ifset is-Ada
    368 @end ifset
    369 
    370 @subheading STATUS CODES:
    371 
    372 @table @b
    373 @item E
    374 The
    375 
    376 @end table
    377 
    378 @subheading DESCRIPTION:
    379 
    380 @subheading NOTES:
     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
    381690
    382691@page
     
    408717
    409718@page
    410 @subsection unlink -
    411 
    412 @subheading CALLING SEQUENCE:
    413 
    414 @ifset is-C
    415 @example
     719@subsection unlink - Removes a directory entry
     720
     721@subheading CALLING SEQUENCE:
     722
     723@ifset is-C
     724@example
     725#include <unistd.h>
     726
    416727int unlink(
    417 );
    418 @end example
    419 @end ifset
    420 
    421 @ifset is-Ada
    422 @end ifset
    423 
    424 @subheading STATUS CODES:
    425 
    426 @table @b
    427 @item E
    428 The
    429 
    430 @end table
    431 
    432 @subheading DESCRIPTION:
    433 
    434 @subheading NOTES:
     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
    435767
    436768@page
     
    462794
    463795@page
    464 @subsection rename -
    465 
    466 @subheading CALLING SEQUENCE:
    467 
    468 @ifset is-C
    469 @example
    470 int rename(
    471 );
    472 @end example
    473 @end ifset
    474 
    475 @ifset is-Ada
    476 @end ifset
    477 
    478 @subheading STATUS CODES:
    479 
    480 @table @b
    481 @item E
    482 The
    483 
    484 @end table
    485 
    486 @subheading DESCRIPTION:
    487 
    488 @subheading NOTES:
    489 
    490 @page
    491 @subsection stat -
    492 
    493 @subheading CALLING SEQUENCE:
    494 
    495 @ifset is-C
    496 @example
    497 int stat(
    498 );
    499 @end example
    500 @end ifset
    501 
    502 @ifset is-Ada
    503 @end ifset
    504 
    505 @subheading STATUS CODES:
    506 
    507 @table @b
    508 @item E
    509 The
    510 
    511 @end table
    512 
    513 @subheading DESCRIPTION:
    514 
    515 @subheading NOTES:
     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
    516915
    517916@page
     
    570969
    571970@page
    572 @subsection chmod -
    573 
    574 @subheading CALLING SEQUENCE:
    575 
    576 @ifset is-C
    577 @example
     971@subsection chmod - Changes file mode.
     972
     973@subheading CALLING SEQUENCE:
     974
     975@ifset is-C
     976@example
     977#include <sys/types.h>
     978#include <sys/stat.h>
     979
    578980int chmod(
    579 );
    580 @end example
    581 @end ifset
    582 
    583 @ifset is-Ada
    584 @end ifset
    585 
    586 @subheading STATUS CODES:
    587 
    588 @table @b
    589 @item E
    590 The
    591 
    592 @end table
    593 
    594 @subheading DESCRIPTION:
     981  const char *path,
     982  mode_t      mode
     983);
     984@end example
     985@end ifset
     986
     987@ifset is-Ada
     988@end ifset
     989
     990@subheading STATUS CODES:
     991
     992@table @b
     993@item EACCES
     994Search permission is denied for a directory in a file's path prefix
     995@item ENAMETOOLONG
     996Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
     997effect.
     998@item ENOENT
     999A file or directory does not exist.
     1000@item ENOTDIR
     1001A component of the specified pathname was not a directory when a directory
     1002was expected.
     1003@item EPERM
     1004Operation is not permitted.  Process does not have the appropriate priviledges
     1005or permissions to perform the requested operations.
     1006@item EROFS
     1007Read-only file system.
     1008
     1009@end table
     1010
     1011@subheading DESCRIPTION:
     1012
     1013Set the file permission bits, the set user ID bit, and the set group ID bit
     1014for the file named by @code{path} to @code{mode}.  If the effective user ID
     1015does not match the owner of the file and the calling process does not have
     1016the appropriate privileges, @code{chmod()} returns -1 and sets @code{errno} to
     1017@code{EPERM}.
    5951018
    5961019@subheading NOTES:
     
    6241047
    6251048@page
    626 @subsection chown -
    627 
    628 @subheading CALLING SEQUENCE:
    629 
    630 @ifset is-C
    631 @example
     1049@subsection chown - Changes the owner and/or group of a file.
     1050
     1051@subheading CALLING SEQUENCE:
     1052
     1053@ifset is-C
     1054@example
     1055#include <sys/types.h>
     1056#include <unistd.h>
     1057
    6321058int chown(
    633 );
    634 @end example
    635 @end ifset
    636 
    637 @ifset is-Ada
    638 @end ifset
    639 
    640 @subheading STATUS CODES:
    641 
    642 @table @b
    643 @item E
    644 The
    645 
    646 @end table
    647 
    648 @subheading DESCRIPTION:
    649 
    650 @subheading NOTES:
     1059  const char *path,
     1060  uid_t       owner,
     1061  gid_t       group
     1062);
     1063@end example
     1064@end ifset
     1065
     1066@ifset is-Ada
     1067@end ifset
     1068
     1069@subheading STATUS CODES:
     1070
     1071@table @b
     1072@item EACCES
     1073Search permission is denied for a directory in a file's path prefix
     1074@item EINVAL
     1075Invalid argument
     1076@item ENAMETOOLONG
     1077Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
     1078effect.
     1079@item ENOENT
     1080A file or directory does not exist.
     1081@item ENOTDIR
     1082A component of the specified pathname was not a directory when a directory
     1083was expected.
     1084@item EPERM
     1085Operation is not permitted.  Process does not have the appropriate priviledges
     1086or permissions to perform the requested operations.
     1087@item EROFS
     1088Read-only file system.
     1089
     1090@end table
     1091
     1092@subheading DESCRIPTION:
     1093
     1094The user ID and group ID of the file named by @code{path} are set to
     1095@code{owner} and @code{path}, respectively.
     1096
     1097For regular files, the set group ID (S_ISGID) and set user ID (S_ISUID)
     1098bits are cleared.
     1099
     1100Some systems consider it a security violation to allow the owner of a file to
     1101be changed,  If users are billed for disk space usage, loaning a file to
     1102another user could result in incorrect billing.  The @code{chown()} function
     1103may be restricted to privileged users for some or all files.  The group ID can
     1104still be changed to one of the supplementary group IDs.
     1105
     1106@subheading NOTES:
     1107
     1108This function may be restricted for some file.  The @code{pathconf} function
     1109can be used to test the _PC_CHOWN_RESTRICTED flag.
     1110
     1111
    6511112
    6521113@page
Note: See TracChangeset for help on using the changeset viewer.