Changeset 08142b48 in rtems


Ignore:
Timestamp:
Sep 12, 1998, 3:57:18 PM (23 years ago)
Author:
Wade A Smith <warm38@…>
Branches:
4.10, 4.11, 4.8, 4.9, 5, master
Children:
433c5585
Parents:
bfcf4cb3
Message:

Documented the following routines added to the Configuration Space
Management: readdir, open, umask, link, mkdir, unlink, chmod, and chown.,

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/new_chapters/confspace.t

    rbfcf4cb3 r08142b48  
    3131@item @code{cfg_children} - Get Node Entries
    3232@item @code{cfg_mark} - Set Configuration Space Option
    33 @item @code{cfg_close} - Close a Configuration Space
     33@item @code{readdir} - Reads a directory
     34@item @code{umask} - Sets a file creation mask
     35@item @code{link} - Creates a link to a file
     36@item @code{unlink} - Removes a directory entry
     37@item @code{mkdir} - Makes a directory
     38@item @code{open} - Opens a file
     39@item @code{chmod} - Changes file mode
     40@item @code{chown} - Changes the owner and/or group of a file
    3441@end itemize
    3542
     
    11241131The @code{_POSIX_CFG} feature flag is defined to indicate
    11251132this service is available.
     1133
     1134@page
     1135@subsection readdir - Reads a directory
     1136
     1137@subheading CALLING SEQUENCE:
     1138
     1139@ifset is-C
     1140@example
     1141#include <sys/types.h>
     1142#include <dirent.h>
     1143
     1144struct dirent *readdir(
     1145  DIR   *dirp
     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 EBADF
     1157Invalid file descriptor
     1158
     1159@end table
     1160
     1161@subheading DESCRIPTION:
     1162
     1163The @code{readdir} function returns a pointer to a structure @code{dirent}
     1164representing the next directory entry from the directory stream pointed to
     1165by @code{dirp}.  On end-of-file, NULL is returned.
     1166
     1167The @code{readdir} function may (or may not) return entries for . or .. Your
     1168program should tolerate reading dot and dot-dot but not require them.
     1169
     1170The data pointed to be @code{readdir} may be overwritten by another call to
     1171@code{readdir} for the same directory stream.  It will not be overwritten by
     1172a call for another directory.
     1173
     1174@subheading NOTES:
     1175
     1176If ptr is not a pointer returned by @code{malloc}, @code{calloc}, or
     1177@code{realloc} or has been deallocated with @code{free} or @code{realloc},
     1178the results are not portable and are probably disastrous.
     1179
     1180@page
     1181@subsection open - Opens a file
     1182
     1183@subheading CALLING SEQUENCE:
     1184
     1185@ifset is-C
     1186@example
     1187#include <sys/types.h>
     1188#include <sys/stat.h>
     1189#include <fcntl.h>
     1190
     1191int open(
     1192   const char *path,
     1193   int         oflag,
     1194   mode_t      mode
     1195);
     1196@end example
     1197@end ifset
     1198
     1199@ifset is-Ada
     1200@end ifset
     1201
     1202@subheading STATUS CODES:
     1203
     1204@table @b
     1205@item EACCES
     1206Search permission is denied for a directory in a file's path prefix
     1207@item EEXIST
     1208The named file already exists.
     1209@item EINTR
     1210Function was interrupted by a signal.
     1211@item EISDIR
     1212Attempt to open a directory for writing or to rename a file to be a
     1213directory.
     1214@item EMFILE
     1215Too many file descriptors are in use by this process.
     1216@item ENAMETOOLONG
     1217Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
     1218effect.
     1219@item ENFILE
     1220Too many files are currently open in the system.
     1221@item ENOENT
     1222A file or directory does not exist.
     1223@item ENOSPC
     1224No space left on disk.
     1225@item ENOTDIR
     1226A component of the specified pathname was not a directory when a directory
     1227was expected.
     1228@item ENXIO
     1229No such device.  This error may also occur when a device is not ready, for
     1230example, a tape drive is off-line.
     1231@item EROFS
     1232Read-only file system.
     1233@end table
     1234
     1235@subheading DESCRIPTION:
     1236
     1237The @code{open} function establishes a connection between a file and a file
     1238descriptor.  The file descriptor is a small integer that is used by I/O
     1239functions to reference the file.  The @code{path} argument points to the
     1240pathname for the file.
     1241
     1242The @code{oflag} argument is the bitwise inclusive OR of the values of
     1243symbolic constants.  The programmer must specify exactly one of the following
     1244three symbols:
     1245
     1246@table @b
     1247@item O_RDONLY
     1248Open for reading only.
     1249
     1250@item O_WRONLY
     1251Open for writing only.
     1252
     1253@item O_RDWR
     1254Open for reading and writing.
     1255
     1256@end table
     1257
     1258Any combination of the following symbols may also be used.
     1259
     1260@table @b
     1261@item O_APPEND
     1262Set the file offset to the end-of-file prior to each write.
     1263
     1264@item O_CREAT
     1265If the file does not exist, allow it to be created.  This flag indicates
     1266that the @code{mode} argument is present in the call to @code{open}.
     1267
     1268@item O_EXCL
     1269This flag may be used only if O_CREAT is also set.  It causes the call
     1270to @code{open} to fail if the file already exists.
     1271
     1272@item O_NOCTTY
     1273If @code{path} identifies a terminal, this flag prevents that teminal from
     1274becoming the controlling terminal for thi9s process.  See Chapter 8 for a
     1275description of terminal I/O.
     1276
     1277@item O_NONBLOCK
     1278Do no wait for the device or file to be ready or available.  After the file
     1279is open, the @code{read} and @code{write} calls return immediately.  If the
     1280process would be delayed in the read or write opermation, -1 is returned and
     1281@code{errno} is set to @code{EAGAIN} instead of blocking the caller.
     1282
     1283@item O_TRUNC
     1284This flag should be used only on ordinary files opened for writing.  It
     1285causes the file to be tuncated to zero length..
     1286
     1287@end table
     1288
     1289Upon successful completion, @code{open} returns a non-negative file
     1290descriptor.
     1291
     1292@subheading NOTES:
     1293
     1294@page
     1295@subsection umask - Sets a file creation mask.
     1296
     1297@subheading CALLING SEQUENCE:
     1298
     1299@ifset is-C
     1300@example
     1301#include <sys/types.h>
     1302#include <sys/stat.h>
     1303
     1304mode_t umask(
     1305  mode_t cmask
     1306);
     1307@end example
     1308@end ifset
     1309
     1310@ifset is-Ada
     1311@end ifset
     1312
     1313@subheading STATUS CODES:
     1314
     1315@subheading DESCRIPTION:
     1316
     1317The @code{umask} function sets the process file creation mask to @code{cmask}.
     1318The file creation mask is used during @code{open}, @code{creat}, @code{mkdir},
     1319@code{mkfifo} calls to turn off permission bits in the @code{mode} argument.
     1320Bit positions that are set in @code{cmask} are cleared in the mode of the
     1321created file.
     1322
     1323The file creation mask is inherited across @code{fork} and @code{exec} calls.
     1324This makes it possible to alter the default permission bits of created files.
     1325
     1326@subheading NOTES:
     1327
     1328The @code{cmask} argument should have only permission bits set.  All other
     1329bits should be zero.
     1330
     1331@page
     1332@subsection link - Creates a link to a file
     1333
     1334@subheading CALLING SEQUENCE:
     1335
     1336@ifset is-C
     1337@example
     1338#include <unistd.h>
     1339
     1340int link(
     1341  const char *existing,
     1342  const char *new
     1343);
     1344@end example
     1345@end ifset
     1346
     1347@ifset is-Ada
     1348@end ifset
     1349
     1350@subheading STATUS CODES:
     1351
     1352@table @b
     1353@item EACCES
     1354Search permission is denied for a directory in a file's path prefix
     1355@item EEXIST
     1356The named file already exists.
     1357@item EMLINK
     1358The number of links would exceed @code{LINK_MAX}.
     1359@item ENAMETOOLONG
     1360Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
     1361effect.
     1362@item ENOENT
     1363A file or directory does not exist.
     1364@item ENOSPC
     1365No space left on disk.
     1366@item ENOTDIR
     1367A component of the specified pathname was not a directory when a directory
     1368was expected.
     1369@item EPERM
     1370Operation is not permitted.  Process does not have the appropriate priviledges
     1371or permissions to perform the requested operations.
     1372@item EROFS
     1373Read-only file system.
     1374@item EXDEV
     1375Attempt to link a file to another file system.
     1376
     1377@end table
     1378
     1379@subheading DESCRIPTION:
     1380
     1381The @code{link} function atomically creates a new link for an existing file
     1382and increments the link count for the file.
     1383
     1384If the @code{link} function fails, no directories are modified.
     1385
     1386The @code{existing} argument should not be a directory.
     1387
     1388The callder may (or may not) need permission to access the existing file.
     1389
     1390@subheading NOTES:
     1391
     1392@page
     1393@subsection unlink - Removes a directory entry
     1394
     1395@subheading CALLING SEQUENCE:
     1396
     1397@ifset is-C
     1398@example
     1399#include <unistd.h>
     1400
     1401int unlink(
     1402  const char path
     1403);
     1404@end example
     1405@end ifset
     1406
     1407@ifset is-Ada
     1408@end ifset
     1409
     1410@subheading STATUS CODES:
     1411
     1412@table @b
     1413@item EACCES
     1414Search permission is denied for a directory in a file's path prefix
     1415@item EBUSY
     1416The directory is in use.
     1417@item ENAMETOOLONG
     1418Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
     1419effect.
     1420@item ENOENT
     1421A file or directory does not exist.
     1422@item ENOTDIR
     1423A component of the specified pathname was not a directory when a directory
     1424was expected.
     1425@item EPERM
     1426Operation is not permitted.  Process does not have the appropriate priviledges
     1427or permissions to perform the requested operations.
     1428@item EROFS
     1429Read-only file system.
     1430
     1431@end table
     1432
     1433@subheading DESCRIPTION:
     1434
     1435The @code{unlink} function removes the link named by @{code} and decrements the
     1436link count of the file referenced by the link.  When the link count goes to zero
     1437and no process has the file open, the space occupied by the file is freed and the
     1438file is no longer accessible.
     1439
     1440@subheading NOTES:
     1441
     1442@page
     1443@subsection mkdir - Makes a directory
     1444
     1445@subheading CALLING SEQUENCE:
     1446
     1447@ifset is-C
     1448@example
     1449#include <sys/types.h>
     1450#include <sys/stat.h>
     1451
     1452int mkdir(
     1453  const char *path,
     1454  mode_t      mode
     1455);
     1456@end example
     1457@end ifset
     1458
     1459@ifset is-Ada
     1460@end ifset
     1461
     1462@subheading STATUS CODES:
     1463
     1464@table @b
     1465@item EACCES
     1466Search permission is denied for a directory in a file's path prefix
     1467@item EEXIST
     1468The name file already exist. 
     1469@item EMLINK
     1470The number of links would exceed LINK_MAX
     1471@item ENAMETOOLONG
     1472Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
     1473effect.
     1474@item ENOENT
     1475A file or directory does not exist.
     1476@item ENOSPC
     1477No space left on disk.
     1478@item ENOTDIR
     1479A component of the specified pathname was not a directory when a directory
     1480was expected.
     1481@item EROFS
     1482Read-only file system.
     1483
     1484@end table
     1485
     1486@subheading DESCRIPTION:
     1487
     1488The @code{mkdir} function creates a new diectory named @code{path}.  The
     1489permission bits (modified by the file creation mask) are set from @code{mode}.
     1490The owner and group IDs for the directory are set from the effective user ID
     1491and group ID.
     1492
     1493The new directory may (or may not) contain entries for. and .. but is otherwise
     1494empty.
     1495
     1496@subheading NOTES:
     1497
     1498@page
     1499@subsection chmod - Changes file mode.
     1500
     1501@subheading CALLING SEQUENCE:
     1502
     1503@ifset is-C
     1504@example
     1505#include <sys/types.h>
     1506#include <sys/stat.h>
     1507
     1508int chmod(
     1509  const char *path,
     1510  mode_t      mode
     1511);
     1512@end example
     1513@end ifset
     1514
     1515@ifset is-Ada
     1516@end ifset
     1517
     1518@subheading STATUS CODES:
     1519
     1520@table @b
     1521@item EACCES
     1522Search permission is denied for a directory in a file's path prefix
     1523@item ENAMETOOLONG
     1524Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
     1525effect.
     1526@item ENOENT
     1527A file or directory does not exist.
     1528@item ENOTDIR
     1529A component of the specified pathname was not a directory when a directory
     1530was expected.
     1531@item EPERM
     1532Operation is not permitted.  Process does not have the appropriate priviledges
     1533or permissions to perform the requested operations.
     1534@item EROFS
     1535Read-only file system.
     1536
     1537@end table
     1538
     1539@subheading DESCRIPTION:
     1540
     1541Set the file permission bits, the set user ID bit, and the set group ID bit
     1542for the file named by @code{path} to @code{mode}.  If the effective user ID
     1543does not match the owner of the file and the calling process does not have
     1544the appropriate privileges, @code{chmod} returns -1 and sets @code{errno} to
     1545@code{EPERM}.
     1546
     1547@subheading NOTES:
     1548
     1549@page
     1550@subsection chown - Changes the owner and/or group of a file.
     1551
     1552@subheading CALLING SEQUENCE:
     1553
     1554@ifset is-C
     1555@example
     1556#include <sys/types.h>
     1557#include <unistd.h>
     1558
     1559int chown(
     1560  const char *path,
     1561  uid_t       owner,
     1562  gid_t       group
     1563);
     1564@end example
     1565@end ifset
     1566
     1567@ifset is-Ada
     1568@end ifset
     1569
     1570@subheading STATUS CODES:
     1571
     1572@table @b
     1573@item EACCES
     1574Search permission is denied for a directory in a file's path prefix
     1575@item EINVAL
     1576Invalid argument
     1577@item ENAMETOOLONG
     1578Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
     1579effect.
     1580@item ENOENT
     1581A file or directory does not exist.
     1582@item ENOTDIR
     1583A component of the specified pathname was not a directory when a directory
     1584was expected.
     1585@item EPERM
     1586Operation is not permitted.  Process does not have the appropriate priviledges
     1587or permissions to perform the requested operations.
     1588@item EROFS
     1589Read-only file system.
     1590
     1591@end table
     1592
     1593@subheading DESCRIPTION:
     1594
     1595The user ID and group ID of the file named by @code{path} are set to
     1596@cdoe{owner} and @code{path}, respectively.
     1597
     1598For regular files, the set group ID (S_ISGID) and set user ID (S_ISUID)
     1599bits are cleared.
     1600
     1601Some systems consider it a security violation to allow the owner of a file to
     1602be changed,  If users are billed for disk space usage, loaning a file to
     1603another user could result in incorrect billing.  The @code{chown} function
     1604may be restricted to privileged users for some or all files.  The group ID can
     1605still be changed to one of the supplementary group IDs.
     1606
     1607@subheading NOTES:
     1608
     1609This function may be restricted for some file.  The @code{pathconf} function
     1610can be used to test the _PC_CHOWN_RESTRICTED flag.
     1611
     1612
Note: See TracChangeset for help on using the changeset viewer.