| blob | 5a6475e86eb130303a19eaf5883ed74a48c03c1f |
1 .\" $NetBSD: fs.5,v 1.16 2005/08/05 13:20:05 jmmv Exp $
2 .\"
3 .\" Copyright (c) 1983, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)fs.5 8.2 (Berkeley) 4/19/94
31 .\"
32 .Dd July 27, 2001
33 .Dt FS 5
34 .Os
35 .Sh NAME
36 .Nm fs ,
37 .Nm inode
38 .Nd format of file system volume
39 .Sh SYNOPSIS
40 .In sys/param.h
41 .In ufs/ffs/fs.h
42 .In ufs/ufs/inode.h
43 .Sh DESCRIPTION
44 The files
45 .Aq Pa ufs/ffs/fs.h
46 and
47 .Aq Pa ufs/ufs/inode.h
48 declare several structures and define variables and macros
49 which are used to create and manage the underlying format of
50 file system objects on random access devices (disks).
51 .Pp
52 The block size and number of blocks which
53 comprise a file system are parameters of the file system.
54 Sectors beginning at
55 .Dv BBLOCK
56 and continuing for
57 .Dv BBSIZE
58 are used
59 for a disklabel and for some hardware primary
60 and secondary bootstrapping programs.
61 .Pp
62 The actual file system begins at sector
63 .Dv SBLOCK
64 with the
65 .Em super-block
66 that is of size
67 .Dv SBSIZE .
68 The following structure described the super-block and is
69 from the file
70 .Aq Pa ufs/ffs/fs.h :
71 .Bd -literal
72 #define FS_MAGIC 0x011954
73 struct fs {
74 int32_t fs_firstfield; /* historic file system linked list, */
75 int32_t fs_unused_1; /* used for incore super blocks */
76 int32_t fs_sblkno; /* addr of super-block in filesys */
77 int32_t fs_cblkno; /* offset of cyl-block in filesys */
78 int32_t fs_iblkno; /* offset of inode-blocks in filesys */
79 int32_t fs_dblkno; /* offset of first data after cg */
80 int32_t fs_old_cgoffset; /* cylinder group offset in cylinder */
81 int32_t fs_old_cgmask; /* used to calc mod fs_ntrak */
82 int32_t fs_old_time; /* last time written */
83 int32_t fs_old_size; /* number of blocks in fs */
84 int32_t fs_old_dsize; /* number of data blocks in fs */
85 int32_t fs_ncg; /* number of cylinder groups */
86 int32_t fs_bsize; /* size of basic blocks in fs */
87 int32_t fs_fsize; /* size of frag blocks in fs */
88 int32_t fs_frag; /* number of frags in a block in fs */
89 /* these are configuration parameters */
90 int32_t fs_minfree; /* minimum percentage of free blocks */
91 int32_t fs_old_rotdelay; /* num of ms for optimal next block */
92 int32_t fs_old_rps; /* disk revolutions per second */
93 /* these fields can be computed from the others */
94 int32_t fs_bmask; /* ``blkoff'' calc of blk offsets */
95 int32_t fs_fmask; /* ``fragoff'' calc of frag offsets */
96 int32_t fs_bshift; /* ``lblkno'' calc of logical blkno */
97 int32_t fs_fshift; /* ``numfrags'' calc number of frags */
98 /* these are configuration parameters */
99 int32_t fs_maxcontig; /* max number of contiguous blks */
100 int32_t fs_maxbpg; /* max number of blks per cyl group */
101 /* these fields can be computed from the others */
102 int32_t fs_fragshift; /* block to frag shift */
103 int32_t fs_fsbtodb; /* fsbtodb and dbtofsb shift constant */
104 int32_t fs_sbsize; /* actual size of super block */
105 int32_t fs_spare1[2]; /* old fs_csmask */
106 /* old fs_csshift */
107 int32_t fs_nindir; /* value of NINDIR */
108 int32_t fs_inopb; /* value of INOPB */
109 int32_t fs_old_nspf; /* value of NSPF */
110 /* yet another configuration parameter */
111 int32_t fs_optim; /* optimization preference, see below */
112 /* these fields are derived from the hardware */
113 int32_t fs_old_npsect; /* # sectors/track including spares */
114 int32_t fs_old_interleave; /* hardware sector interleave */
115 int32_t fs_old_trackskew; /* sector 0 skew, per track */
116 /* fs_id takes the space of unused fs_headswitch and fs_trkseek fields */
117 int32_t fs_id[2]; /* unique file system id */
118 /* sizes determined by number of cylinder groups and their sizes */
119 int32_t fs_old_csaddr; /* blk addr of cyl grp summary area */
120 int32_t fs_cssize; /* size of cyl grp summary area */
121 int32_t fs_cgsize; /* cylinder group size */
122 /* these fields are derived from the hardware */
123 int32_t fs_spare2; /* old fs_ntrak */
124 int32_t fs_old_nsect; /* sectors per track */
125 int32_t fs_old_spc; /* sectors per cylinder */
126 int32_t fs_old_ncyl; /* cylinders in file system */
127 int32_t fs_old_cpg; /* cylinders per group */
128 int32_t fs_ipg; /* inodes per group */
129 int32_t fs_fpg; /* blocks per group * fs_frag */
130 /* this data must be re-computed after crashes */
131 struct csum fs_old_cstotal; /* cylinder summary information */
132 /* these fields are cleared at mount time */
133 int8_t fs_fmod; /* super block modified flag */
134 int8_t fs_clean; /* file system is clean flag */
135 int8_t fs_ronly; /* mounted read-only flag */
136 uint8_t fs_old_flags; /* see FS_ flags below */
137 u_char fs_fsmnt[MAXMNTLEN]; /* name mounted on */
138 u_char fs_volname[MAXVOLLEN]; /* volume name */
139 uint64_t fs_swuid; /* system-wide uid */
140 int32_t fs_pad;
141 /* these fields retain the current block allocation info */
142 int32_t fs_cgrotor; /* last cg searched (UNUSED) */
143 void *fs_ocsp[NOCSPTRS];/* padding; was list of fs_cs buffers */
144 uint8_t *fs_contigdirs; /* # of contiguously allocated dirs */
145 struct csum *fs_csp; /* cg summary info buffer for fs_cs */
146 int32_t *fs_maxcluster; /* max cluster in each cyl group */
147 u_char *fs_active; /* used by snapshots to track fs */
148 int32_t fs_old_cpc; /* cyl per cycle in postbl */
149 /* this area is otherwise allocated unless fs_old_flags & FS_FLAGS_UPDATED */
150 int32_t fs_maxbsize; /* maximum blocking factor permitted */
151 int64_t fs_sparecon64[17]; /* old rotation block list head */
152 int64_t fs_sblockloc; /* byte offset of standard superblock */
153 struct csum_total fs_cstotal; /* cylinder summary information */
154 int64_t fs_time; /* last time written */
155 int64_t fs_size; /* number of blocks in fs */
156 int64_t fs_dsize; /* number of data blocks in fs */
157 int64_t fs_csaddr; /* blk addr of cyl grp summary area */
158 int64_t fs_pendingblocks; /* blocks in process of being freed */
159 int32_t fs_pendinginodes; /* inodes in process of being freed */
160 int32_t fs_snapinum[FSMAXSNAP]; /* list of snapshot inode numbers */
161 /* back to stuff that has been around a while */
162 int32_t fs_avgfilesize; /* expected average file size */
163 int32_t fs_avgfpdir; /* expected # of files per directory */
164 int32_t fs_save_cgsize; /* save real cg size to use fs_bsize */
165 int32_t fs_sparecon32[26]; /* reserved for future constants */
166 uint32_t fs_flags; /* see FS_ flags below */
167 /* back to stuff that has been around a while (again) */
168 int32_t fs_contigsumsize; /* size of cluster summary array */
169 int32_t fs_maxsymlinklen; /* max length of an internal symlink */
170 int32_t fs_old_inodefmt; /* format of on-disk inodes */
171 uint64_t fs_maxfilesize; /* maximum representable file size */
172 int64_t fs_qbmask; /* ~fs_bmask for use with 64-bit size */
173 int64_t fs_qfmask; /* ~fs_fmask for use with 64-bit size */
174 int32_t fs_state; /* validate fs_clean field (UNUSED) */
175 int32_t fs_old_postblformat; /* format of positional layout tables */
176 int32_t fs_old_nrpos; /* number of rotational positions */
177 int32_t fs_spare5[2]; /* old fs_postbloff */
178 /* old fs_rotbloff */
179 int32_t fs_magic; /* magic number */
180 };
181 .Ed
182 .Pp
183 Each disk drive contains some number of file systems.
184 A file system consists of a number of cylinder groups.
185 Each cylinder group has inodes and data.
186 .Pp
187 A file system is described by its super-block, which in turn
188 describes the cylinder groups.
189 The super-block is critical data and is replicated in each cylinder
190 group to protect against catastrophic loss.
191 This is done at file system creation time and the critical super-block
192 data does not change, so the copies need not be referenced further
193 unless disaster strikes.
194 .Pp
195 Addresses stored in inodes are capable of addressing fragments
196 of `blocks'.
197 File system blocks of at most size
198 .Dv MAXBSIZE
199 can
200 be optionally broken into 2, 4, or 8 pieces, each of which is
201 addressable; these pieces may be
202 .Dv DEV_BSIZE ,
203 or some multiple of
204 a
205 .Dv DEV_BSIZE
206 unit.
207 .Pp
208 Large files consist of exclusively large data blocks.
209 To avoid undue wasted disk space, the last data block of a small
210 file is allocated as only as many fragments of a large block as
211 are necessary.
212 The file system format retains only a single pointer to such a
213 fragment, which is a piece of a single large block that has been divided.
214 The size of such a fragment is determinable from
215 information in the inode, using the
216 .Fn blksize fs ip lbn
217 macro.
218 .Pp
219 The file system records space availability at the fragment level;
220 to determine block availability, aligned fragments are examined.
221 .Pp
222 The root inode is the root of the file system.
223 Inode 0 can't be used for normal purposes and
224 historically bad blocks were linked to inode 1,
225 thus the root inode is 2 (inode 1 is no longer used for
226 this purpose, however numerous dump tapes make this
227 assumption, so we are stuck with it).
228 .Pp
229 The
230 .Fa fs_minfree
231 element gives the minimum acceptable percentage of file system
232 blocks that may be free.
233 If the freelist drops below this level
234 only the super-user may continue to allocate blocks.
235 The
236 .Fa fs_minfree
237 element
238 may be set to 0 if no reserve of free blocks is deemed necessary,
239 however severe performance degradations will be observed if the
240 file system is run at greater than 90% full; thus the default
241 value of
242 .Fa fs_minfree
243 is 10%.
244 .Pp
245 Empirically the best trade-off between block fragmentation and
246 overall disk utilization at a loading of 90% comes with a
247 fragmentation of 8, thus the default fragment size is an eighth
248 of the block size.
249 .Pp
250 The element
251 .Fa fs_optim
252 specifies whether the file system should try to minimize the time spent
253 allocating blocks, or if it should attempt to minimize the space
254 fragmentation on the disk.
255 If the value of fs_minfree (see above) is less than 10%,
256 then the file system defaults to optimizing for space to avoid
257 running out of full sized blocks.
258 If the value of minfree is greater than or equal to 10%,
259 fragmentation is unlikely to be problematical, and
260 the file system defaults to optimizing for time.
261 .Pp
262 .Em Cylinder group related limits :
263 Each cylinder keeps track of the availability of blocks at different
264 rotational positions, so that sequential blocks can be laid out
265 with minimum rotational latency.
266 With the default of 8 distinguished
267 rotational positions, the resolution of the
268 summary information is 2ms for a typical 3600 rpm drive.
269 .Pp
270 The element
271 .Fa fs_rotdelay
272 gives the minimum number of milliseconds to initiate
273 another disk transfer on the same cylinder.
274 It is used in determining the rotationally optimal
275 layout for disk blocks within a file;
276 the default value for
277 .Fa fs_rotdelay
278 is 2ms.
279 .Pp
280 Each file system has a statically allocated number of inodes,
281 determined by its size and the desired number of file data bytes per
282 inode at the time it was created. See
283 .Xr newfs 8
284 for details on how to set this (and other) filesystem parameters.
285 By default, the inode allocation strategy is extremely conservative.
286 .Pp
287 .Dv MINBSIZE
288 is the smallest allowable block size.
289 With a
290 .Dv MINBSIZE
291 of 4096
292 it is possible to create files of size
293 2^32 with only two levels of indirection.
294 .Dv MINBSIZE
295 must be big enough to hold a cylinder group block,
296 thus changes to
297 .Pq Fa struct cg
298 must keep its size within
299 .Dv MINBSIZE .
300 Note that super-blocks are never more than size
301 .Dv SBSIZE .
302 .Pp
303 The path name on which the file system is mounted is maintained in
304 .Fa fs_fsmnt .
305 .Dv MAXMNTLEN
306 defines the amount of space allocated in
307 the super-block for this name.
308 The limit on the amount of summary information per file system
309 is defined by
310 .Dv MAXCSBUFS .
311 For a 4096 byte block size, it is currently parameterized for a
312 maximum of two million cylinders.
313 .Pp
314 Per cylinder group information is summarized in blocks allocated
315 from the first cylinder group's data blocks.
316 These blocks are read in from
317 .Fa fs_csaddr
318 (size
319 .Fa fs_cssize )
320 in addition to the super-block.
321 .Pp
322 .Sy N.B.:
323 .Fn sizeof "struct csum"
324 must be a power of two in order for
325 the
326 .Fn fs_cs
327 macro to work.
328 .Pp
329 The
330 .Em "Super-block for a file system" :
331 The size of the rotational layout tables
332 is limited by the fact that the super-block is of size
333 .Dv SBSIZE .
334 The size of these tables is
335 .Em inversely
336 proportional to the block size of the file system.
337 The size of the tables is increased when sector sizes are not powers
338 of two, as this increases the number of cylinders included before
339 the rotational pattern repeats
340 .Pq Fa fs_cpc .
341 The size of the rotational layout
342 tables is derived from the number of bytes remaining in
343 .Pq Fa struct fs .
344 .Pp
345 The number of blocks of data per cylinder group
346 is limited because cylinder groups are at most one block.
347 The inode and free block tables
348 must fit into a single block after deducting space for
349 the cylinder group structure
350 .Pq Fa struct cg .
351 .Pp
352 The
353 .Em Inode :
354 The inode is the focus of all file activity in the
355 .Ux
356 file system.
357 There is a unique inode allocated
358 for each active file,
359 each current directory, each mounted-on file,
360 text file, and the root.
361 An inode is `named' by its device/i-number pair.
362 For further information, see the include file
363 .Aq Pa ufs/ufs/inode.h .
364 .Sh SEE ALSO
365 .Xr newfs 8
366 .Sh HISTORY
367 A super-block structure named filsys appeared in
368 .At v6 .
369 The file system described in this manual appeared
370 in
371 .Bx 4.2 .