/share/doc/psd/05.sysman/2.2.t

https://bitbucket.org/freebsd/freebsd-head/ · Raku · 470 lines · 470 code · 0 blank · 0 comment · 8 complexity · 6656e71f95ae57acca6b3eba1cf6f592 MD5 · raw file

  1. .\" Copyright (c) 1983, 1993
  2. .\" The Regents of the University of California. All rights reserved.
  3. .\"
  4. .\" Redistribution and use in source and binary forms, with or without
  5. .\" modification, are permitted provided that the following conditions
  6. .\" are met:
  7. .\" 1. Redistributions of source code must retain the above copyright
  8. .\" notice, this list of conditions and the following disclaimer.
  9. .\" 2. Redistributions in binary form must reproduce the above copyright
  10. .\" notice, this list of conditions and the following disclaimer in the
  11. .\" documentation and/or other materials provided with the distribution.
  12. .\" 3. All advertising materials mentioning features or use of this software
  13. .\" must display the following acknowledgement:
  14. .\" This product includes software developed by the University of
  15. .\" California, Berkeley and its contributors.
  16. .\" 4. Neither the name of the University nor the names of its contributors
  17. .\" may be used to endorse or promote products derived from this software
  18. .\" without specific prior written permission.
  19. .\"
  20. .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21. .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22. .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23. .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24. .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25. .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26. .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27. .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28. .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29. .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30. .\" SUCH DAMAGE.
  31. .\"
  32. .\" @(#)2.2.t 8.1 (Berkeley) 6/8/93
  33. .\"
  34. .sh "File system
  35. .NH 3
  36. Overview
  37. .PP
  38. The file system abstraction provides access to a hierarchical
  39. file system structure.
  40. The file system contains directories (each of which may contain
  41. other sub-directories) as well as files and references to other
  42. objects such as devices and inter-process communications sockets.
  43. .PP
  44. Each file is organized as a linear array of bytes. No record
  45. boundaries or system related information is present in
  46. a file.
  47. Files may be read and written in a random-access fashion.
  48. The user may read the data in a directory as though
  49. it were an ordinary file to determine the names of the contained files,
  50. but only the system may write into the directories.
  51. The file system stores only a small amount of ownership, protection and usage
  52. information with a file.
  53. .NH 3
  54. Naming
  55. .PP
  56. The file system calls take \fIpath name\fP arguments.
  57. These consist of a zero or more component \fIfile names\fP
  58. separated by ``/\^'' characters, where each file name
  59. is up to 255 ASCII characters excluding null and ``/\^''.
  60. .PP
  61. Each process always has two naming contexts: one for the
  62. root directory of the file system and one for the
  63. current working directory. These are used
  64. by the system in the filename translation process.
  65. If a path name begins with a ``/\^'', it is called
  66. a full path name and interpreted relative to the root directory context.
  67. If the path name does not begin with a ``/\^'' it is called
  68. a relative path name and interpreted relative to the current directory
  69. context.
  70. .PP
  71. The system limits
  72. the total length of a path name to 1024 characters.
  73. .PP
  74. The file name ``..'' in each directory refers to
  75. the parent directory of that directory.
  76. The parent directory of the root of the file system is always that directory.
  77. .PP
  78. The calls
  79. .DS
  80. chdir(path);
  81. char *path;
  82. chroot(path)
  83. char *path;
  84. .DE
  85. change the current working directory and root directory context of a process.
  86. Only the super-user can change the root directory context of a process.
  87. .NH 3
  88. Creation and removal
  89. .PP
  90. The file system allows directories, files, special devices,
  91. and ``portals'' to be created and removed from the file system.
  92. .NH 4
  93. Directory creation and removal
  94. .PP
  95. A directory is created with the \fImkdir\fP system call:
  96. .DS
  97. mkdir(path, mode);
  98. char *path; int mode;
  99. .DE
  100. where the mode is defined as for files (see below).
  101. Directories are removed with the \fIrmdir\fP system call:
  102. .DS
  103. rmdir(path);
  104. char *path;
  105. .DE
  106. A directory must be empty if it is to be deleted.
  107. .NH 4
  108. File creation
  109. .PP
  110. Files are created with the \fIopen\fP system call,
  111. .DS
  112. fd = open(path, oflag, mode);
  113. result int fd; char *path; int oflag, mode;
  114. .DE
  115. The \fIpath\fP parameter specifies the name of the
  116. file to be created. The \fIoflag\fP parameter must
  117. include O_CREAT from below to cause the file to be created.
  118. Bits for \fIoflag\fP are
  119. defined in \fI<sys/file.h>\fP:
  120. .DS
  121. ._d
  122. #define O_RDONLY 000 /* open for reading */
  123. #define O_WRONLY 001 /* open for writing */
  124. #define O_RDWR 002 /* open for read & write */
  125. #define O_NDELAY 004 /* non-blocking open */
  126. #define O_APPEND 010 /* append on each write */
  127. #define O_CREAT 01000 /* open with file create */
  128. #define O_TRUNC 02000 /* open with truncation */
  129. #define O_EXCL 04000 /* error on create if file exists */
  130. .DE
  131. .PP
  132. One of O_RDONLY, O_WRONLY and O_RDWR should be specified,
  133. indicating what types of operations are desired to be performed
  134. on the open file. The operations will be checked against the user's
  135. access rights to the file before allowing the \fIopen\fP to succeed.
  136. Specifying O_APPEND causes writes to automatically append to the
  137. file.
  138. The flag O_CREAT causes the file to be created if it does not
  139. exist, owned by the current user
  140. and the group of the containing directory.
  141. The protection for the new file is specified in \fImode\fP.
  142. The file mode is used as a three digit octal number.
  143. Each digit encodes read access as 4, write access as 2 and execute
  144. access as 1, or'ed together. The 0700 bits describe owner
  145. access, the 070 bits describe the access rights for processes in the same
  146. group as the file, and the 07 bits describe the access rights
  147. for other processes.
  148. .PP
  149. If the open specifies to create the file with O_EXCL
  150. and the file already exists, then the \fIopen\fP will fail
  151. without affecting the file in any way. This provides a
  152. simple exclusive access facility.
  153. If the file exists but is a symbolic link, the open will fail
  154. regardless of the existence of the file specified by the link.
  155. .NH 4
  156. Creating references to devices
  157. .PP
  158. The file system allows entries which reference peripheral devices.
  159. Peripherals are distinguished as \fIblock\fP or \fIcharacter\fP
  160. devices according by their ability to support block-oriented
  161. operations.
  162. Devices are identified by their ``major'' and ``minor''
  163. device numbers. The major device number determines the kind
  164. of peripheral it is, while the minor device number indicates
  165. one of possibly many peripherals of that kind.
  166. Structured devices have all operations performed internally
  167. in ``block'' quantities while
  168. unstructured devices often have a number of
  169. special \fIioctl\fP operations, and may have input and output
  170. performed in varying units.
  171. The \fImknod\fP call creates special entries:
  172. .DS
  173. mknod(path, mode, dev);
  174. char *path; int mode, dev;
  175. .DE
  176. where \fImode\fP is formed from the object type
  177. and access permissions. The parameter \fIdev\fP is a configuration
  178. dependent parameter used to identify specific character or
  179. block I/O devices.
  180. .NH 4
  181. Portal creation\(dg
  182. .PP
  183. .FS
  184. \(dg The \fIportal\fP call is not implemented in 4.3BSD.
  185. .FE
  186. The call
  187. .DS
  188. fd = portal(name, server, param, dtype, protocol, domain, socktype)
  189. result int fd; char *name, *server, *param; int dtype, protocol;
  190. int domain, socktype;
  191. .DE
  192. places a \fIname\fP in the file system name space that causes connection to a
  193. server process when the name is used.
  194. The portal call returns an active portal in \fIfd\fP as though an
  195. access had occurred to activate an inactive portal, as now described.
  196. .PP
  197. When an inactive portal is accessed, the system sets up a socket
  198. of the specified \fIsocktype\fP in the specified communications
  199. \fIdomain\fP (see section 2.3), and creates the \fIserver\fP process,
  200. giving it the specified \fIparam\fP as argument to help it identify
  201. the portal, and also giving it the newly created socket as descriptor
  202. number 0. The accessor of the portal will create a socket in the same
  203. \fIdomain\fP and \fIconnect\fP to the server. The user will then
  204. \fIwrap\fP the socket in the specified \fIprotocol\fP to create an object of
  205. the required descriptor type \fIdtype\fP and proceed with the
  206. operation which was in progress before the portal was encountered.
  207. .PP
  208. While the server process holds the socket (which it received as \fIfd\fP
  209. from the \fIportal\fP call on descriptor 0 at activation) further references
  210. will result in connections being made to the same socket.
  211. .NH 4
  212. File, device, and portal removal
  213. .PP
  214. A reference to a file, special device or portal may be removed with the
  215. \fIunlink\fP call,
  216. .DS
  217. unlink(path);
  218. char *path;
  219. .DE
  220. The caller must have write access to the directory in which
  221. the file is located for this call to be successful.
  222. .NH 3
  223. Reading and modifying file attributes
  224. .PP
  225. Detailed information about the attributes of a file
  226. may be obtained with the calls:
  227. .DS
  228. #include <sys/stat.h>
  229. stat(path, stb);
  230. char *path; result struct stat *stb;
  231. fstat(fd, stb);
  232. int fd; result struct stat *stb;
  233. .DE
  234. The \fIstat\fP structure includes the file
  235. type, protection, ownership, access times,
  236. size, and a count of hard links.
  237. If the file is a symbolic link, then the status of the link
  238. itself (rather than the file the link references)
  239. may be found using the \fIlstat\fP call:
  240. .DS
  241. lstat(path, stb);
  242. char *path; result struct stat *stb;
  243. .DE
  244. .PP
  245. Newly created files are assigned the user id of the
  246. process that created it and the group id of the directory
  247. in which it was created. The ownership of a file may
  248. be changed by either of the calls
  249. .DS
  250. chown(path, owner, group);
  251. char *path; int owner, group;
  252. fchown(fd, owner, group);
  253. int fd, owner, group;
  254. .DE
  255. .PP
  256. In addition to ownership, each file has three levels of access
  257. protection associated with it. These levels are owner relative,
  258. group relative, and global (all users and groups). Each level
  259. of access has separate indicators for read permission, write
  260. permission, and execute permission.
  261. The protection bits associated with a file may be set by either
  262. of the calls:
  263. .DS
  264. chmod(path, mode);
  265. char *path; int mode;
  266. fchmod(fd, mode);
  267. int fd, mode;
  268. .DE
  269. where \fImode\fP is a value indicating the new protection
  270. of the file, as listed in section 2.2.3.2.
  271. .PP
  272. Finally, the access and modify times on a file may be set by the call:
  273. .DS
  274. utimes(path, tvp)
  275. char *path; struct timeval *tvp[2];
  276. .DE
  277. This is particularly useful when moving files between media, to
  278. preserve relationships between the times the file was modified.
  279. .NH 3
  280. Links and renaming
  281. .PP
  282. Links allow multiple names for a file
  283. to exist. Links exist independently of the file linked to.
  284. .PP
  285. Two types of links exist, \fIhard\fP links and \fIsymbolic\fP
  286. links. A hard link is a reference counting mechanism that
  287. allows a file to have multiple names within the same file
  288. system. Symbolic links cause string substitution
  289. during the pathname interpretation process.
  290. .PP
  291. Hard links and symbolic links have different
  292. properties. A hard link insures the target
  293. file will always be accessible, even after its original
  294. directory entry is removed; no such guarantee exists for a symbolic link.
  295. Symbolic links can span file systems boundaries.
  296. .PP
  297. The following calls create a new link, named \fIpath2\fP,
  298. to \fIpath1\fP:
  299. .DS
  300. link(path1, path2);
  301. char *path1, *path2;
  302. symlink(path1, path2);
  303. char *path1, *path2;
  304. .DE
  305. The \fIunlink\fP primitive may be used to remove
  306. either type of link.
  307. .PP
  308. If a file is a symbolic link, the ``value'' of the
  309. link may be read with the \fIreadlink\fP call,
  310. .DS
  311. len = readlink(path, buf, bufsize);
  312. result int len; result char *path, *buf; int bufsize;
  313. .DE
  314. This call returns, in \fIbuf\fP, the null-terminated string
  315. substituted into pathnames passing through \fIpath\fP\|.
  316. .PP
  317. Atomic renaming of file system resident objects is possible
  318. with the \fIrename\fP call:
  319. .DS
  320. rename(oldname, newname);
  321. char *oldname, *newname;
  322. .DE
  323. where both \fIoldname\fP and \fInewname\fP must be
  324. in the same file system.
  325. If \fInewname\fP exists and is a directory, then it must be empty.
  326. .NH 3
  327. Extension and truncation
  328. .PP
  329. Files are created with zero length and may be extended
  330. simply by writing or appending to them. While a file is
  331. open the system maintains a pointer into the file
  332. indicating the current location in the file associated with
  333. the descriptor. This pointer may be moved about in the
  334. file in a random access fashion.
  335. To set the current offset into a file, the \fIlseek\fP
  336. call may be used,
  337. .DS
  338. oldoffset = lseek(fd, offset, type);
  339. result off_t oldoffset; int fd; off_t offset; int type;
  340. .DE
  341. where \fItype\fP is given in \fI<sys/file.h>\fP as one of:
  342. .DS
  343. ._d
  344. #define L_SET 0 /* set absolute file offset */
  345. #define L_INCR 1 /* set file offset relative to current position */
  346. #define L_XTND 2 /* set offset relative to end-of-file */
  347. .DE
  348. The call ``lseek(fd, 0, L_INCR)''
  349. returns the current offset into the file.
  350. .PP
  351. Files may have ``holes'' in them. Holes are void areas in the
  352. linear extent of the file where data has never been
  353. written. These may be created by seeking to
  354. a location in a file past the current end-of-file and writing.
  355. Holes are treated by the system as zero valued bytes.
  356. .PP
  357. A file may be truncated with either of the calls:
  358. .DS
  359. truncate(path, length);
  360. char *path; int length;
  361. ftruncate(fd, length);
  362. int fd, length;
  363. .DE
  364. reducing the size of the specified file to \fIlength\fP bytes.
  365. .NH 3
  366. Checking accessibility
  367. .PP
  368. A process running with
  369. different real and effective user ids
  370. may interrogate the accessibility of a file to the
  371. real user by using
  372. the \fIaccess\fP call:
  373. .DS
  374. accessible = access(path, how);
  375. result int accessible; char *path; int how;
  376. .DE
  377. Here \fIhow\fP is constructed by or'ing the following bits, defined
  378. in \fI<sys/file.h>\fP:
  379. .DS
  380. ._d
  381. #define F_OK 0 /* file exists */
  382. #define X_OK 1 /* file is executable */
  383. #define W_OK 2 /* file is writable */
  384. #define R_OK 4 /* file is readable */
  385. .DE
  386. The presence or absence of advisory locks does not affect the
  387. result of \fIaccess\fP\|.
  388. .NH 3
  389. Locking
  390. .PP
  391. The file system provides basic facilities that allow cooperating processes
  392. to synchronize their access to shared files. A process may
  393. place an advisory \fIread\fP or \fIwrite\fP lock on a file,
  394. so that other cooperating processes may avoid interfering
  395. with the process' access. This simple mechanism
  396. provides locking with file granularity. More granular
  397. locking can be built using the IPC facilities to provide a lock
  398. manager.
  399. The system does not force processes to obey the locks;
  400. they are of an advisory nature only.
  401. .PP
  402. Locking is performed after an \fIopen\fP call by applying the
  403. \fIflock\fP primitive,
  404. .DS
  405. flock(fd, how);
  406. int fd, how;
  407. .DE
  408. where the \fIhow\fP parameter is formed from bits defined in \fI<sys/file.h>\fP:
  409. .DS
  410. ._d
  411. #define LOCK_SH 1 /* shared lock */
  412. #define LOCK_EX 2 /* exclusive lock */
  413. #define LOCK_NB 4 /* don't block when locking */
  414. #define LOCK_UN 8 /* unlock */
  415. .DE
  416. Successive lock calls may be used to increase or
  417. decrease the level of locking. If an object is currently
  418. locked by another process when a \fIflock\fP call is made,
  419. the caller will be blocked until the current lock owner
  420. releases the lock; this may be avoided by including LOCK_NB
  421. in the \fIhow\fP parameter.
  422. Specifying LOCK_UN removes all locks associated with the descriptor.
  423. Advisory locks held by a process are automatically deleted when
  424. the process terminates.
  425. .NH 3
  426. Disk quotas
  427. .PP
  428. As an optional facility, each file system may be requested to
  429. impose limits on a user's disk usage.
  430. Two quantities are limited: the total amount of disk space which
  431. a user may allocate in a file system and the total number of files
  432. a user may create in a file system. Quotas are expressed as
  433. \fIhard\fP limits and \fIsoft\fP limits. A hard limit is
  434. always imposed; if a user would exceed a hard limit, the operation
  435. which caused the resource request will fail. A soft limit results
  436. in the user receiving a warning message, but with allocation succeeding.
  437. Facilities are provided to turn soft limits into hard limits if a
  438. user has exceeded a soft limit for an unreasonable period of time.
  439. .PP
  440. To enable disk quotas on a file system the \fIsetquota\fP call
  441. is used:
  442. .DS
  443. setquota(special, file)
  444. char *special, *file;
  445. .DE
  446. where \fIspecial\fP refers to a structured device file where
  447. a mounted file system exists, and
  448. \fIfile\fP refers to a disk quota file (residing on the file
  449. system associated with \fIspecial\fP) from which user quotas
  450. should be obtained. The format of the disk quota file is
  451. implementation dependent.
  452. .PP
  453. To manipulate disk quotas the \fIquota\fP call is provided:
  454. .DS
  455. #include <sys/quota.h>
  456. quota(cmd, uid, arg, addr)
  457. int cmd, uid, arg; caddr_t addr;
  458. .DE
  459. The indicated \fIcmd\fP is applied to the user ID \fIuid\fP.
  460. The parameters \fIarg\fP and \fIaddr\fP are command specific.
  461. The file \fI<sys/quota.h>\fP contains definitions pertinent to the
  462. use of this call.