Changeset 8dd54b6 in rtems


Ignore:
Timestamp:
Sep 30, 1998, 8:21:45 PM (21 years ago)
Author:
Wade A Smith <warm38@…>
Branches:
4.10, 4.11, 4.8, 4.9, master
Children:
f65b0903
Parents:
b931d05a
Message:

Updated the STATUS CODE section for the routines in this file.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/new_chapters/confspace.t

    rb931d05a r8dd54b6  
    8686@subheading STATUS CODES:
    8787
     88A successful call to @code{cfg_mount()} returns a value of zero
     89and an unsuccessful call returns the @code{errno}.
     90
    8891@table @b
    8992@item EPERM
     
    9497
    9598@item EEXIST
    96 The file specified by the file argument does not exist
     99The file specified by the @code{file} argument does not exist
    97100
    98101@item ENAMETOOLONG
     
    105108
    106109@item ENOTDIR
    107 A component of the file path prefix is not a directory.
     110A component of the @code{file} path prefix is not a directory.
    108111
    109112@item EBUSY
    110 The configuration space defined by file is already mounted.
     113The configuration space defined by @code{file} is already mounted.
    111114
    112115@item EINVAL
     
    158161@subheading STATUS CODES:
    159162
     163A successful call to @code{cfg_umount()} returns a value of zero
     164and an unsuccessful call returns the @code{errno}.
     165
    160166@table @b
    161167@item EPERM
     
    166172
    167173@item ENOENT
    168 A component of cfgpath does not exist.
     174A component of @code{cfgpath} does not exist.
    169175
    170176@item ENAMETOOLONG
     
    184190@item ELOOP
    185191A node appears more than once in the path specified by the
    186 @code{cfg_path} argument
     192@code{cfgpath} argument
    187193
    188194@item ELOOP
     
    226232@subheading STATUS CODES:
    227233
     234A successful call to @code{cfg_mknod()} returns a value of zero
     235and an unsuccessful call returns the @code{errno}.
     236
    228237@table @b
    229238@item ENAMETOOLONG
     
    238247Search permission is denied for a component of the path prefix.
    239248
    240 @item ELOOP
    241 Too many symbolic links were encountered in translating the
    242 pathname.
    243249
    244250@item EPERM
     
    256262@item ELOOP
    257263A node appears more than once in the path specified by the
    258 @cdoe{cfg_path} argument
     264@code{cfg_path} argument
    259265
    260266@item ELOOP
    261267More than @code{SYMLOOP_MAX} symbolic links were encountered during
    262 resolution of the cfgpath argument.
     268resolution of the @code{cfgpath} argument.
    263269
    264270@item EROFS
     
    301307@subheading STATUS CODES:
    302308
     309A successful call to @code{cfg_get()} returns a value of zero
     310and an unsuccessful call returns the @code{errno}.
     311
    303312@table @b
    304313@item ENAMETOOLONG
     
    308317
    309318@item ENOENT
    310 A component of cfgpath does not exist.
     319A component of @code{cfgpath} does not exist.
    311320
    312321@item EACCES
     
    318327@item ELOOP
    319328A node appears more than once in the path specified by the
    320 cfg_path argument
     329@code{cfgpath} argument
    321330
    322331@item ELOOP
    323332More than @code{SYMLOOP_MAX} symbolic links were encountered during
    324 resolution of the cfgpath argument.
    325 
    326 @end table
    327 
    328 @subheading DESCRIPTION:
    329 
    330 The @code{cfg_get} function stores the value attribute of the
     333resolution of the @code{cfgpath} argument.
     334
     335@end table
     336
     337@subheading DESCRIPTION:
     338
     339The @code{cfg_get()} function stores the value attribute of the
    331340configuration node identified by @code{cfgpath}, into the buffer
    332341described by the @code{value} pointer.
     
    357366
    358367@subheading STATUS CODES:
     368
     369A successful call to @code{cfg_set()} returns a value of zero
     370and an unsuccessful call returns the @code{errno}.
    359371
    360372@table @b
     
    365377
    366378@item ENOENT
    367 A component of cfgpath does not exist
     379A component of @code{cfgpath} does not exist
    368380
    369381@item EACCES
     
    375387@item ELOOP
    376388A node appears more than once in the path specified by the
    377 cfg-path argument.
     389@code{cfgpath} argument.
    378390
    379391@item ELOOP
     
    385397@subheading DESCRIPTION:
    386398
    387 The @code{cfg_set} function stores the value specified by the
     399The @code{cfg_set()} function stores the value specified by the
    388400@code{value} argument in the configuration node defined by the
    389401@code{cfgpath} argument.
     
    414426
    415427@subheading STATUS CODES:
     428
     429A successful call to @code{cfg_link()} returns a value of zero
     430and an unsuccessful call returns the @code{errno}.
    416431
    417432@table @b
     
    432447
    433448@item ENOENT
    434 The node named by src does not exist.
     449The node named by @code{src} does not exist.
    435450
    436451@item EEXIST
    437 The node named by dest does exist.
     452The node named by @code{dest} does exist.
    438453
    439454@item EPERM
    440455The calling process does not have the appropriate privilege to
    441 modify the node indicated by the src argument.
     456modify the node indicated by the @code{src} argument.
    442457
    443458@item EXDEV
    444 The link named by dest and the node named by src are from different
     459The link named by @code{dest} and the node named by @code{src} are from different
    445460configuration spaces.
    446461
     
    458473configuration space.
    459474
    460 @item ELOOP
    461 A node appears more than once in the path specified by the
    462 cfg-path argument.
    463 
    464 @item ELOOP
    465 More than @code{SYMLOOP_MAX} symbolic links were encountered during
    466 resolution of the cfgpath argument.
    467 
    468 @end table
    469 
    470 @subheading DESCRIPTION:
    471 
    472 The @code{src} and @code{dest}arguments point to pathnames which
    473 name existing nodes.  The @code{cfg_link} function atomically creates
     475@end table
     476
     477@subheading DESCRIPTION:
     478
     479The @code{src} and @code{dest} arguments point to pathnames which
     480name existing nodes.  The @code{cfg_link()} function atomically creates
    474481a link between specified nodes, and increment by one the link count
    475482of the node specified by the @code{src} argument.
    476483
    477 If the @code{cfg_link} function fails, no link is created, and the
     484If the @code{cfg_link()} function fails, no link is created, and the
    478485link count of the node remains unchanged by this function call.
    479486
    480 This implementation may require that the calling process has permission
    481 to access the specified nodes.
    482487
    483488@subheading NOTES:
     
    505510
    506511@subheading STATUS CODES:
     512
     513A successful call to @code{cfg_unlink()} returns a value of zero
     514and an unsuccessful call returns the @code{errno}.
    507515
    508516@table @b
     
    511519or an entire path name exceed @code{PATH_MAX} characters.
    512520
    513 @item ENOENT
    514 The named  node does not exist.
    515 
    516521@item EACCES
    517522Search permission is denied on the node containing the link to
     
    523528
    524529@item ENOENT
    525 A component of cfgpath does not exist.
     530A component of @code{cfgpath} does not exist.
    526531
    527532@item EPERM
    528533The calling process does not have the appropriate privilege to
    529 modify the node indicated by the path prefix of the cfgpath
     534modify the node indicated by the path prefix of the @code{cfgpath}
    530535argument.
    531536
     
    543548@item ELOOP
    544549A node appears more than once in the path specified by the
    545 cfg-path argument.
     550@code{cfgpath} argument.
    546551
    547552@item ELOOP
     
    553558@subheading DESCRIPTION:
    554559
    555 The @code{cfg_unlink} function removes the link between the node
     560The @code{cfg_unlink()} function removes the link between the node
    556561specified by the @code{cfgpath} path prefix and the parent node
    557562specified by @code{cfgpath}, and decrements the link count
     
    589594@subheading STATUS CODES:
    590595
     596A successful call to @code{cfg_open()} returns a value of zero
     597and an unsuccessful call returns the @code{errno}.
     598
    591599@table @b
    592600@item EACCES
     
    606614
    607615@item EINVAL
    608 Either both or neither of CFG_LOGICAL and CFG_PHYSICAL are
    609 specified by the options argument
     616Either both or neither of @code{CFG_LOGICAL} and @code{CFG_PHYSICAL} are
     617specified by the @code{options} argument
    610618
    611619@item ENOMEM
     
    614622@item ELOOP
    615623More than @code{SYMLOOP_MAX} symbolic links were encountered during
    616 resolution of the pathnames argument.
     624resolution of the @code{pathnames} argument.
    617625
    618626@item ENAMETOOLONG
    619627As a result of encountering a symbolic link in resolution of the
    620 pathname specified by the pathnames argument, the length of
     628pathname specified by the @code{pathnames} argument, the length of
    621629the substituted pathname string exceeded @code{PATH_MAX}.
    622630
     
    625633@subheading DESCRIPTION:
    626634
    627 The @code{cfg_open} function opens a configuration traversal stream
     635The @code{cfg_open()} function opens a configuration traversal stream
    628636rooted in the configuration nodes name by the @code{pathnames} argument.
    629637It stores a pointer to a CFG object that represents that stream at
     
    670678pre-order return, followed by the return of structures
    671679referencing all its descendants, followed by a post-order
    672 return, shall be done.
     680return, is done.
    673681
    674682@item CFG_XDEV
     
    680688@end table
    681689
    682 The @code{cfg_open} argument @code{compar} is either a NULL or point
     690The @code{cfg_open()} argument @code{compar} is either a NULL or point
    683691to a function that is called with two pointers to pointers to CFGENT
    684692structures that returns less than, equal to , or greater than zero if
     
    692700directories encountered during the traversal are returned, and the order
    693701of traversal when more than one node is specified in the @code{pathnames}
    694 argument to @code{cfg_open}.  If a comparison routine is specified, the
     702argument to @code{cfg_open()}.  If a comparison routine is specified, the
    695703order of traversal is from the least to the greatest.  If the @code{compar}
    696 argument is NULL, the order of traversal shall be as listed in the
     704argument is NULL, the order of traversal shall is listed in the
    697705@code{pathnames} argument.
    698706
     
    723731@subheading STATUS CODES:
    724732
     733A successful call to @code{cfg_read()} returns a value of zero
     734and an unsuccessful call returns the @code{errno}.
     735
    725736@table @b
    726737@item EACCES
     
    728739
    729740@item EBADF
    730 The cfgp argument does not refer to an open configuration
     741The @code{cfgp} argument does not refer to an open configuration
    731742space.
    732743
     
    736747
    737748@item ENOENT
    738 A named node does not exist.
     749A named @code{node} does not exist.
    739750
    740751@item ENOMEM
     
    754765@subheading DESCRIPTION:
    755766
    756 The @code{cfg_read} function returns a pointer to a CFGENT structure
     767The @code{cfg_read()} function returns a pointer to a CFGENT structure
    757768representing a node in the configuration space to which @code{cfgp}
    758769refers.  The returned pointer is stored at the location indicated
     
    760771
    761772The child nodes of each node in the configuration tree is returned
    762 by @code{cfg_read}.  If a comparison routine is specified to the
    763 @code{cfg_open} function, the order of return of the child nodes is
    764 as specified by the routine, from least to greatest.  Otherwise
    765 the order of return is unspecified.
     773by @code{cfg_read()}.  If a comparison routine was specified to the
     774@code{cfg_open()} function, the order of return of the child nodes is
     775as specified by the @code{compar} routine, from least to greatest. 
     776Otherwise, the order of return is unspecified.
    766777
    767778Structures referencing nodes with children is returned by the
    768 function @code{cfg_read} at least twice [unless the application
    769 specifies otherwise with @code{cfg_mark}]-once immediately before
     779function @code{cfg_read()} at least twice [unless the application
     780specifies otherwise with @code{cfg_mark()}]-once immediately before
    770781the structures representing their descendants, are returned
    771782(pre-order), and once immediately after structures representing all
     
    783794@item cfg_parent
    784795A pointer to the structure returned by the
    785 @code{cfg_read} function for the node that contains
     796@code{cfg_read()} function for the node that contains
    786797the entry for the current node.  A @code{cfg_parent}
    787798structure is provided for the node(s) specified by
    788 the @code{pathnames} argument to the @code{cfg_open}
     799the @code{pathnames} argument to the @code{cfg_open()}
    789800function, but the contents of other than its
    790801@code{cfg_number}, @code{cfg_pointer}, @code{cfg_parent},
     
    793804
    794805@item cfg_link
    795 Upon return from the @code{cfg_children} function, the
     806Upon return from the @code{cfg_children()} function, the
    796807@code{cfg_link} field points to the next CFGENT structure
    797808in a NULL-terminated linked list of CFGENT structures. 
     
    800811
    801812@item cfg_cycle
    802 If the structure being returned by @code{cfg_read}
     813If the structure being returned by @code{cfg_read()}
    803814represents a node that appears in the @code{cfg_parent}
    804815linked list tree, the @code{cfg_cycle} field shall point
     
    810821The @code{cfg_number} field is provided for use by the
    811822application program.  It is initialized to zero for
    812 each new node returned by the @code{cfg_read} function,
     823each new node returned by the @code{cfg_read()} function,
    813824but is not further modified by the configuration space
    814825routines.
     
    817828The @code{cfg_pointer} field is provided for use by the
    818829application program.  It is initialized to NULL for
    819 each new node returned by the @code{cfg_read} function,
     830each new node returned by the @code{cfg_read()} function,
    820831but is not further modified by the configuration
    821832space routines.
     
    823834@item cfg_path
    824835A pathname for the node including and relative to the
    825 argument supplied to the @code{cfg_open} routine for this
     836argument supplied to the @code{cfg_open()} routine for this
    826837configuration space.  This pathname may be longer than
    827838@code{PATH_MAX} bytes.  This pathname is NULL-terminated.
     
    832843@item cfg_pathlen
    833844The length of the string pointed at by the @code{cfg_path}
    834 field when returned by @code{cfg_read}.
     845field when returned by @code{cfg_read()}.
    835846
    836847@item cfg_namelen
     
    842853The @code{cfg_level} field of the @code{cfg_parent}
    843854structure for each of the node(s) specified in the
    844 @code{pathnames} argument to the @code{cfg_open} function
     855@code{pathnames} argument to the @code{cfg_open()} function
    845856is set to 0, and this number is incremented for each
    846857node level descendant.
     
    859870@item CFG_DC
    860871The structure represents a node that is a parent
    861 of the node most recently returned by @code{cfg_read}.
     872of the node most recently returned by @code{cfg_read()}.
    862873The @code{cfg_cycle} field references the structure
    863874previously returned by @code{cfg_read} that is the
     
    898909@end table
    899910
    900 Structures returned by @code{cfg_read} with a @code{cfg_info} field equal
     911Structures returned by @code{cfg_read()} with a @code{cfg_info} field equal
    901912to CFG_D is accessible until a subsequent call, on the same
    902 configuration traversal stream, to @code{cfg_close}, or to @code{cfg_read}
     913configuration traversal stream, to @code{cfg_close()}, or to @code{cfg_read()}
    903914after they have been returned by the @code{cfg_read} function in
    904 post-order.  Structures returned by @code{cfg_read} with an
     915post-order.  Structures returned by @code{cfg_read()} with an
    905916@code{cfg_info} field not equal to CFG_D is accessible until a subsequent
    906 call, on the same configuration traversal stream, to @code{cfg_close}
    907 or @code{cfg_read}.
     917call, on the same configuration traversal stream, to @code{cfg_close()}
     918or @code{cfg_read()}.
    908919
    909920The content of the @code{cfg_path} field is specified only for the
    910 structure most recently returned by @code{cfg_read}.
     921structure most recently returned by @code{cfg_read()}.
    911922
    912923The specified fields in structures in the list representing nodes for
    913 which structures have previously been returned by @code{cfg_children},
    914 is identical to those returned by @code{cfg_children}, except that
     924which structures have previously been returned by @code{cfg_children()},
     925is identical to those returned by @code{cfg_children()}, except that
    915926the contents of the @code{cfg_path} and @code{cfg_pathlen} fields are
    916927unspecified.
     
    943954@subheading STATUS CODES:
    944955
     956A successful call to @code{cfg_children()} returns a value of zero
     957and an unsuccessful call returns the @code{errno}.
     958
    945959@table @b
    946960@item EACCES
     
    948962
    949963@item EBADF
    950 The cfgp argument does not refer to an open configuration space.
     964The @code{cfgp} argument does not refer to an open configuration space.
    951965
    952966@item ELOOP
     
    960974
    961975@item EINVAL
    962 The specified value of the options argument is invalid.
     976The specified value of the @code{options} argument is invalid.
    963977
    964978@item ENOENT
     
    972986@subheading DESCRIPTION:
    973987
    974 The first @code{cfg_children} call after a @code{cfg_read} returns
     988The first @code{cfg_children()} call after a @code{cfg_read()} returns
    975989information about the first node without children under the node
    976 returned by @code{cfg_read}.  Subsequent calls to @code{cfg_children}
    977 without the intervening @code{cfg_read} shall return information
     990returned by @code{cfg_read()}.  Subsequent calls to @code{cfg_children()}
     991without the intervening @code{cfg_read()} shall return information
    978992about the remaining nodes without children under that same node.
    979993
    980 If @code{cfg_read} has not yet been called for the configuration
    981 traversal stream represented by @code{cfgp}, @code{cfg_children}
     994If @code{cfg_read()} has not yet been called for the configuration
     995traversal stream represented by @code{cfgp}, @code{cfg_children()}
    982996returns a pointer to the first entry in a list of the nodes
    983 represented by the @code{pathnames} argument to @code{cfg_open}.
     997represented by the @code{pathnames} argument to @code{cfg_open()}.
    984998
    985999In either case, the list is NULL-terminated, ordered by the
    9861000user-specified comparison function, if any, and linked through the
    987 cfg_link field.
     1001@code{cfg_link} field.
    9881002
    9891003@subheading NOTES:
     
    10141028@subheading STATUS CODES:
    10151029
     1030A successful call to @code{cfg_mark()} returns a value of zero
     1031and an unsuccessful call returns the @code{errno}.
     1032
    10161033@table @b
    10171034@item EINVAL
    1018 The specified combination of the cfgp and f arguments is not
     1035The specified combination of the @code{cfgp} and @code{f} arguments is not
    10191036supported by the implementation.
    10201037
    10211038@item EINVAL
    1022 The specified value of the options argument is invalid.
    1023 
    1024 @end table
    1025 
    1026 @subheading DESCRIPTION:
    1027 
    1028 The @code{cfg_mark} function modifies the subsequent behavior of
    1029 the cfg functions with regard to the node referenced by the structure
     1039The specified value of the @code{options} argument is invalid.
     1040
     1041@end table
     1042
     1043@subheading DESCRIPTION:
     1044
     1045The @code{cfg_mark()} function modifies the subsequent behavior of
     1046the @code{cfg} functions with regard to the node referenced by the structure
    10301047pointed to by the argument @code{f} or the configuration space referenced
    10311048by the structure pointed to by the argument @code{cfgp}.
     
    10411058If the @code{cfgp} argument is non-NULL, or the @code{f}
    10421059argument is NULL, or the structure referenced by @code{f}
    1043 is not the one most recently returned by @code{cfg_read},
    1044 @code{cfg_mark} returns an error.  Otherwise, the next
    1045 call to the @code{cfg_read} function returns the structure
     1060is not the one most recently returned by @code{cfg_read()},
     1061@code{cfg_mark()} returns an error.  Otherwise, the next
     1062call to the @code{cfg_read()} function returns the structure
    10461063referenced by @code{f} with the @code{cfg_info} field
    10471064reinitialized.  Subsequent behavior of the @code{cfg}
     
    10541071is not one of those specified as accessible, or the structure
    10551072referenced by @code{f} is not for a node of type pre-order
    1056 node, @code{cfg_mark} returns an error.  Otherwise, no
     1073node, @code{cfg_mark()} returns an error.  Otherwise, no
    10571074more structures for the node referenced by @code{f} or its
    1058 descendants are returned by the @code{cfg_read} function.
     1075descendants are returned by the @code{cfg_read()} function.
    10591076
    10601077@item CFG_FOLLOW
     
    10631080is not one of those specified as accessible, or the structure
    10641081referenced by @code{f} is not for a node of type symbolic link,
    1065 @code{cfg_mark} returns an error.  Otherwise, the next
    1066 call to the @code{cfg_read} function returns the structure
     1082@code{cfg_mark()} returns an error.  Otherwise, the next
     1083call to the @code{cfg_read()} function returns the structure
    10671084referenced by @code{f} with the @code{cfg_info} field reset
    10681085to reflect the target of the symbolic link instead of the
     
    10751092
    10761093If the target of the symbolic link does not exist, the fields
    1077 of the structure by @code{cfg_read} shall be unmodified, except
     1094of the structure by @code{cfg_read()} shall be unmodified, except
    10781095that the @code{cfg_info} field shall be reset to @code{CFG_SLNONE}.
    10791096
     
    11031120@subheading STATUS CODES:
    11041121
     1122A successful call to @code{cfg_close()} returns a value of zero
     1123and an unsuccessful call returns the @code{errno}.
     1124
    11051125@table @b
    11061126@item EBADF
    1107 The cfgp argument does not refer to an open configuration space
     1127The @code{cfgp} argument does not refer to an open configuration space
    11081128traversal stream.
    11091129
     
    11121132@subheading DESCRIPTION:
    11131133
    1114 The @code{cfg_close} function closes a configuration space transversal
     1134The @code{cfg_close()} function closes a configuration space transversal
    11151135stream represented by the CFG structure pointed at by the @code{cfgp}
    11161136argument.  All system resources allocated for this configuration space
     
    11521172@subheading DESCRIPTION:
    11531173
    1154 The @code{cfg_readdir} function returns a pointer to a structure @code{dirent}
     1174The @code{cfg_readdir()} function returns a pointer to a structure @code{dirent}
    11551175representing the next directory entry from the directory stream pointed to
    11561176by @code{dirp}.  On end-of-file, NULL is returned.
    11571177
    1158 The @code{cfg_readdir} function may (or may not) return entries for . or .. Your
     1178The @code{cfg_readdir()} function may (or may not) return entries for . or .. Your
    11591179program should tolerate reading dot and dot-dot but not require them.
    11601180
    1161 The data pointed to be @code{cfg_readdir} may be overwritten by another call to
    1162 @code{readdir} for the same directory stream.  It will not be overwritten by
     1181The data pointed to be @code{cfg_readdir()} may be overwritten by another call to
     1182@code{readdir()} for the same directory stream.  It will not be overwritten by
    11631183a call for another directory.
    11641184
    11651185@subheading NOTES:
    11661186
    1167 If ptr is not a pointer returned by @code{malloc}, @code{calloc}, or
    1168 @code{realloc} or has been deallocated with @code{free} or @code{realloc},
     1187If @code{ptr} is not a pointer returned by @code{malloc()}, @code{calloc()}, or
     1188@code{realloc()} or has been deallocated with @code{free()} or @code{realloc()},
    11691189the results are not portable and are probably disastrous.
    11701190
    1171 @page
    1172 @subsection open - Opens a file
     1191This function is not defined in the POSIX specification.  It is an extension
     1192provided by this implementation.
     1193
     1194@page
     1195@subsection cfg_umask - Sets a file creation mask.
    11731196
    11741197@subheading CALLING SEQUENCE:
     
    11781201#include <sys/types.h>
    11791202#include <sys/stat.h>
    1180 #include <fcntl.h>
    1181 
    1182 int open(
    1183    const char *path,
    1184    int         oflag,
    1185    mode_t      mode
    1186 );
    1187 @end example
    1188 @end ifset
    1189 
    1190 @ifset is-Ada
    1191 @end ifset
    1192 
    1193 @subheading STATUS CODES:
    1194 
    1195 @table @b
    1196 @item EACCES
    1197 Search permission is denied for a directory in a file's path prefix
    1198 @item EEXIST
    1199 The named file already exists.
    1200 @item EINTR
    1201 Function was interrupted by a signal.
    1202 @item EISDIR
    1203 Attempt to open a directory for writing or to rename a file to be a
    1204 directory.
    1205 @item EMFILE
    1206 Too many file descriptors are in use by this process.
    1207 @item ENAMETOOLONG
    1208 Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
    1209 effect.
    1210 @item ENFILE
    1211 Too many files are currently open in the system.
    1212 @item ENOENT
    1213 A file or directory does not exist.
    1214 @item ENOSPC
    1215 No space left on disk.
    1216 @item ENOTDIR
    1217 A component of the specified pathname was not a directory when a directory
    1218 was expected.
    1219 @item ENXIO
    1220 No such device.  This error may also occur when a device is not ready, for
    1221 example, a tape drive is off-line.
    1222 @item EROFS
    1223 Read-only file system.
    1224 @end table
    1225 
    1226 @subheading DESCRIPTION:
    1227 
    1228 The @code{open} function establishes a connection between a file and a file
    1229 descriptor.  The file descriptor is a small integer that is used by I/O
    1230 functions to reference the file.  The @code{path} argument points to the
    1231 pathname for the file.
    1232 
    1233 The @code{oflag} argument is the bitwise inclusive OR of the values of
    1234 symbolic constants.  The programmer must specify exactly one of the following
    1235 three symbols:
    1236 
    1237 @table @b
    1238 @item O_RDONLY
    1239 Open for reading only.
    1240 
    1241 @item O_WRONLY
    1242 Open for writing only.
    1243 
    1244 @item O_RDWR
    1245 Open for reading and writing.
    1246 
    1247 @end table
    1248 
    1249 Any combination of the following symbols may also be used.
    1250 
    1251 @table @b
    1252 @item O_APPEND
    1253 Set the file offset to the end-of-file prior to each write.
    1254 
    1255 @item O_CREAT
    1256 If the file does not exist, allow it to be created.  This flag indicates
    1257 that the @code{mode} argument is present in the call to @code{open}.
    1258 
    1259 @item O_EXCL
    1260 This flag may be used only if O_CREAT is also set.  It causes the call
    1261 to @code{open} to fail if the file already exists.
    1262 
    1263 @item O_NOCTTY
    1264 If @code{path} identifies a terminal, this flag prevents that teminal from
    1265 becoming the controlling terminal for thi9s process.  See Chapter 8 for a
    1266 description of terminal I/O.
    1267 
    1268 @item O_NONBLOCK
    1269 Do no wait for the device or file to be ready or available.  After the file
    1270 is open, the @code{read} and @code{write} calls return immediately.  If the
    1271 process would be delayed in the read or write opermation, -1 is returned and
    1272 @code{errno} is set to @code{EAGAIN} instead of blocking the caller.
    1273 
    1274 @item O_TRUNC
    1275 This flag should be used only on ordinary files opened for writing.  It
    1276 causes the file to be tuncated to zero length..
    1277 
    1278 @end table
    1279 
    1280 Upon successful completion, @code{open} returns a non-negative file
    1281 descriptor.
    1282 
    1283 @subheading NOTES:
    1284 
    1285 @page
    1286 @subsection cfg_umask - Sets a file creation mask.
    1287 
    1288 @subheading CALLING SEQUENCE:
    1289 
    1290 @ifset is-C
    1291 @example
    1292 #include <sys/types.h>
    1293 #include <sys/stat.h>
    12941203
    12951204mode_t cfg_umask(
     
    13061215@subheading DESCRIPTION:
    13071216
    1308 The @code{cfg_umask} function sets the process file creation mask to @code{cmask}.
    1309 The file creation mask is used during @code{open}, @code{creat}, @code{mkdir},
    1310 @code{mkfifo} calls to turn off permission bits in the @code{mode} argument.
     1217The @code{cfg_umask()} function sets the process node creation mask to @code{cmask}.
     1218The file creation mask is used during @code{open()}, @code{creat()}, @code{mkdir()},
     1219@code{mkfifo()} calls to turn off permission bits in the @code{mode} argument.
    13111220Bit positions that are set in @code{cmask} are cleared in the mode of the
    13121221created file.
    13131222
    1314 The file creation mask is inherited across @code{fork} and @code{exec} calls.
     1223The file creation mask is inherited across @code{fork()} and @code{exec()} calls.
    13151224This makes it possible to alter the default permission bits of created files.
    13161225
    1317 @subheading NOTES:
     1226@subheading NOTES: None
    13181227
    13191228The @code{cmask} argument should have only permission bits set.  All other
    13201229bits should be zero.
    1321 
    1322 @page
    1323 @subsection link - Creates a link to a file
    1324 
    1325 @subheading CALLING SEQUENCE:
    1326 
    1327 @ifset is-C
    1328 @example
    1329 #include <unistd.h>
    1330 
    1331 int link(
    1332   const char *existing,
    1333   const char *new
    1334 );
    1335 @end example
    1336 @end ifset
    1337 
    1338 @ifset is-Ada
    1339 @end ifset
    1340 
    1341 @subheading STATUS CODES:
    1342 
    1343 @table @b
    1344 @item EACCES
    1345 Search permission is denied for a directory in a file's path prefix
    1346 @item EEXIST
    1347 The named file already exists.
    1348 @item EMLINK
    1349 The number of links would exceed @code{LINK_MAX}.
    1350 @item ENAMETOOLONG
    1351 Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
    1352 effect.
    1353 @item ENOENT
    1354 A file or directory does not exist.
    1355 @item ENOSPC
    1356 No space left on disk.
    1357 @item ENOTDIR
    1358 A component of the specified pathname was not a directory when a directory
    1359 was expected.
    1360 @item EPERM
    1361 Operation is not permitted.  Process does not have the appropriate priviledges
    1362 or permissions to perform the requested operations.
    1363 @item EROFS
    1364 Read-only file system.
    1365 @item EXDEV
    1366 Attempt to link a file to another file system.
    1367 
    1368 @end table
    1369 
    1370 @subheading DESCRIPTION:
    1371 
    1372 The @code{link} function atomically creates a new link for an existing file
    1373 and increments the link count for the file.
    1374 
    1375 If the @code{link} function fails, no directories are modified.
    1376 
    1377 The @code{existing} argument should not be a directory.
    1378 
    1379 The callder may (or may not) need permission to access the existing file.
    1380 
    1381 @subheading NOTES:
    1382 
    1383 @page
    1384 @subsection unlink - Removes a directory entry
    1385 
    1386 @subheading CALLING SEQUENCE:
    1387 
    1388 @ifset is-C
    1389 @example
    1390 #include <unistd.h>
    1391 
    1392 int unlink(
    1393   const char path
    1394 );
    1395 @end example
    1396 @end ifset
    1397 
    1398 @ifset is-Ada
    1399 @end ifset
    1400 
    1401 @subheading STATUS CODES:
    1402 
    1403 @table @b
    1404 @item EACCES
    1405 Search permission is denied for a directory in a file's path prefix
    1406 @item EBUSY
    1407 The directory is in use.
    1408 @item ENAMETOOLONG
    1409 Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
    1410 effect.
    1411 @item ENOENT
    1412 A file or directory does not exist.
    1413 @item ENOTDIR
    1414 A component of the specified pathname was not a directory when a directory
    1415 was expected.
    1416 @item EPERM
    1417 Operation is not permitted.  Process does not have the appropriate priviledges
    1418 or permissions to perform the requested operations.
    1419 @item EROFS
    1420 Read-only file system.
    1421 
    1422 @end table
    1423 
    1424 @subheading DESCRIPTION:
    1425 
    1426 The @code{unlink} function removes the link named by @{code} and decrements the
    1427 link count of the file referenced by the link.  When the link count goes to zero
    1428 and no process has the file open, the space occupied by the file is freed and the
    1429 file is no longer accessible.
    1430 
    1431 @subheading NOTES:
    1432 
    1433 @page
    1434 @subsection cfg_mkdir - Makes a directory
    1435 
    1436 @subheading CALLING SEQUENCE:
    1437 
    1438 @ifset is-C
    1439 @example
    1440 #include <sys/types.h>
    1441 #include <sys/stat.h>
    1442 
    1443 int cfg_mkdir(
    1444   const char *path,
    1445   mode_t      mode
    1446 );
    1447 @end example
    1448 @end ifset
    1449 
    1450 @ifset is-Ada
    1451 @end ifset
    1452 
    1453 @subheading STATUS CODES:
    1454 
    1455 @table @b
    1456 @item EACCES
    1457 Search permission is denied for a directory in a file's path prefix
    1458 @item EEXIST
    1459 The name file already exist. 
    1460 @item EMLINK
    1461 The number of links would exceed LINK_MAX
    1462 @item ENAMETOOLONG
    1463 Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
    1464 effect.
    1465 @item ENOENT
    1466 A file or directory does not exist.
    1467 @item ENOSPC
    1468 No space left on disk.
    1469 @item ENOTDIR
    1470 A component of the specified pathname was not a directory when a directory
    1471 was expected.
    1472 @item EROFS
    1473 Read-only file system.
    1474 
    1475 @end table
    1476 
    1477 @subheading DESCRIPTION:
    1478 
    1479 The @code{cfg_mkdir} function creates a new diectory named @code{path}.  The
    1480 permission bits (modified by the file creation mask) are set from @code{mode}.
    1481 The owner and group IDs for the directory are set from the effective user ID
    1482 and group ID.
    1483 
    1484 The new directory may (or may not) contain entries for. and .. but is otherwise
    1485 empty.
    1486 
    1487 @subheading NOTES:
    14881230
    14891231@page
     
    15081250
    15091251@subheading STATUS CODES:
     1252
     1253A successful call to @code{cfg_chmod()} returns a value of zero
     1254and an unsuccessful call returns the @code{errno}.
    15101255
    15111256@table @b
     
    15321277Set the file permission bits, the set user ID bit, and the set group ID bit
    15331278for the file named by @code{path} to @code{mode}.  If the effective user ID
    1534 does not match the owner of the file and the calling process does not have
    1535 the appropriate privileges, @code{cfg_chmod} returns -1 and sets @code{errno} to
     1279does not match the owner of the node and the calling process does not have
     1280the appropriate privileges, @code{cfg_chmod()} returns -1 and sets @code{errno} to
    15361281@code{EPERM}.
    15371282
     
    15601305
    15611306@subheading STATUS CODES:
     1307
     1308A successful call to @code{cfg_chown()} returns a value of zero
     1309and an unsuccessful call returns the @code{errno}.
    15621310
    15631311@table @b
     
    15921340Some systems consider it a security violation to allow the owner of a file to
    15931341be changed,  If users are billed for disk space usage, loaning a file to
    1594 another user could result in incorrect billing.  The @code{cfg_chown} function
     1342another user could result in incorrect billing.  The @code{cfg_chown()} function
    15951343may be restricted to privileged users for some or all files.  The group ID can
    15961344still be changed to one of the supplementary group IDs.
Note: See TracChangeset for help on using the changeset viewer.