[apple/hfs.git] / fsck_hfs / fsck_hfs.8

.\" Copyright (c) 2002,2008 Apple Inc. All rights reserved.
.\" 
.\" The contents of this file constitute Original Code as defined in and
.\" are subject to the Apple Public Source License Version 1.1 (the
.\" "License").  You may not use this file except in compliance with the
.\" License.  Please obtain a copy of the License at
.\" http://www.apple.com/publicsource and read it before using this file.
.\" 
.\" This Original Code and all software distributed under the License are
.\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
.\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
.\" License for the specific language governing rights and limitations
.\" under the License.
.\" 
.\"     @(#)fsck_hfs.8
.Dd August 5, 2008
.Dt FSCK_HFS 8
.Os "Mac OS X"
.Sh NAME
.Nm fsck_hfs
.Nd HFS file system consistency check
.Sh SYNOPSIS
.Nm fsck_hfs
.Fl q
.Op Fl df
.Ar special ...
.Nm fsck_hfs
.Fl p
.Op Fl df
.Ar special ...
.Nm fsck_hfs
.Op Fl n | y | r
.Op Fl dfgxlES
.Op Fl D Ar flags
.Op Fl b Ar size
.Op Fl B Ar path
.Op Fl m Ar mode
.Op Fl c Ar size
.Op Fl R Ar flags
.Ar special ...
.Sh DESCRIPTION
.Pp
The
.Nm
utility verifies and repairs standard HFS and HFS+ file systems.
.Pp
The first form of
.Nm
quickly checks the specified file systems to determine whether
they were cleanly unmounted.
.Pp
The second form of
.Nm
preens the specified file systems.
It is normally started by
.Xr fsck 8
run from
.Pa /etc/rc.boot
during automatic reboot, when a HFS file system is detected.
When preening file systems,
.Nm
will fix common inconsistencies for file systems that were not
unmounted cleanly.
If more serious problems are found,
.Nm
does not try to fix them, indicates that it was not
successful, and exits.
.Pp
The third form of
.Nm
checks the specified file systems and tries to repair all
detected inconsistencies.
.Pp
If no options are specified 
.Nm
will always check and attempt to fix the specified file systems.
.Pp
The options are as follows:
.Bl -hang -offset indent
.It Fl c Ar size
Specify the
.Ar size 
of the cache used by  
.Nm
internally.  Bigger 
.Ar size 
can result in better performance but can result in deadlock when
used with 
.Fl l 
option.  Size can be specified as a decimal, octal, or 
hexadecimal number.  If the number ends with a ``k'', ``m'', 
or ``g'', the number is multiplied by 1024 (1K), 1048576 (1M),
or 1073741824 (1G), respectively.  
.It Fl d
Display debugging information.
This option may provide useful information when 
.Nm
cannot repair a damaged file system.
.It Fl D Ar flags
Print extra debugging information.  The
.Ar flags
are a bitmap that control which kind of debug information is printed.
The following values are currently implemented:
.Bl -hang -offset indent -compact
.It 0x0001
Informational messages
.It 0x0002
Error messages
.It 0x0010
Extended attributes related messages
.It 0x0020
Overlapped extents related messages
.El
.It Fl b Ar size
Specify the size, in bytes, of the physical blocks used by the
.Fl B
option.
.It Fl B Ar path
Print the files containing the physical blocks listed in the file
.Ar path .
The file should contain one or more decimal, octal (with leading 0) or
hexadecimal (with leading 0x) numbers separated by white space.  The physical
block numbers are relative to the start of the partition, so if you
have block numbers relative to the start of the device, you will have to
subtract the block number of the start of the partition.  The size of a
physical block is given with the
.Fl b
option; the default is 512 bytes per block.
.It Fl f
When used with the
.Fl p
option, force
.Nm
to check `clean' file systems, otherwise it means force
.Nm
to check and repair journaled HFS+ file systems.
.It Fl g
Causes
.Nm
to generate its output strings in GUI format.
This option is used when another application with a graphical user interface
(like Mac OS X Disk Utility) is invoking the
.Nm
tool.
.It Fl x
Causes
.Nm
to generate its output strings in XML (plist) format.  This option
implies the
.Fl g
option.
.It Fl l
Lock down the file system and perform a test-only check.
This makes it possible to check a file system that is currently mounted,
although no repairs can be made.
.It Fl m Ar mode
Mode is an octal number that will be used to set the permissions for the
lost+found directory when it is created.
The lost+found directory is only created when a volume is repaired and orphaned
files or directories are detected.
.Nm
places orphaned files and directories into the lost+found directory (located
at the root of the volume).
The default mode is 01777.
.It Fl p
Preen the specified file systems.
.It Fl q
Causes
.Nm
to quickly check whether the volume was unmounted cleanly.
If the volume was unmounted cleanly, then the exit status is 0.
If the volume was not unmounted cleanly, then the exit status will be non-zero.
In either case, a message is printed to standard output describing whether the
volume was clean or dirty.
.It Fl y
Always attempt to repair any damage that is found.
.It Fl n
Never attempt to repair any damage that is found.
.It Fl E
Cause
.Nm
to exit (with a value of 47) if it encounters any
major errors.  A ``major error'' is considered one which
would impact using the volume in normal usage; an inconsistency
which would not impact such use is considered ``minor'' for this
option.  Only valid with the
.Fl n
option.
.It Fl S
Cause
.Nm
to scan the entire device looking for I/O errors.  It will
attempt to map the blocks with errors to names, similar to
the
.Fl B
option.
.It Fl R Ar flags
Rebuilds the requested btree.  The following flags are supported:
.Bl -hang -offset indent -compact
.It a
Attribute btree
.It c
Catalog btree
.It e
Extents overflow btree
.El
Rebuilding a btree will only
work if there is enough free space on the file system for the new btree
file, and if
.Nm
is able to traverse each of the nodes in the requested btree successfully.
Rebuilding btrees is not supported on HFS Standard volumes.
.It Fl r
Rebuild the catalog btree.  This is synonymous with
.Fl Rc .
.El
.Pp
Because of inconsistencies between the block device and the buffer cache,
the raw device should always be used.
.Sh EXIT VALUES
.Nm
indicates some status by exit value.  The current list of exit status results
is:
.Bl -hang -offset indent -compact
.It 0
No errors found, or successfully repaired.
.It 3
A quick-check (the
.Fl n
option) found a dirty filesystem; no repairs were made.
.It 4
During boot, the root filesystem was found to be dirty; repairs were
made, and the filesystem was remounted.  The system should be rebooted.
.It 8
A corrupt filesystem was found during a check, or repairs did not succeed.
.It 47
A major error was found with
.Fl E .
.El
.Sh SEE ALSO
.Xr fsck 8
.Sh BUGS
.Nm
is not able to fix some inconsistencies that it detects.
.Sh HISTORY
The
.Nm
command appeared in Mac OS X Server 1.0 .
Commit	Line	Data
51e135ce A	1	.\" Copyright (c) 2002,2008 Apple Inc. All rights reserved.
	2	.\"
	3	.\" The contents of this file constitute Original Code as defined in and
	4	.\" are subject to the Apple Public Source License Version 1.1 (the
	5	.\" "License"). You may not use this file except in compliance with the
	6	.\" License. Please obtain a copy of the License at
	7	.\" http://www.apple.com/publicsource and read it before using this file.
	8	.\"
	9	.\" This Original Code and all software distributed under the License are
	10	.\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	11	.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	12	.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	13	.\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
	14	.\" License for the specific language governing rights and limitations
	15	.\" under the License.
	16	.\"
	17	.\" @(#)fsck_hfs.8
	18	.Dd August 5, 2008
	19	.Dt FSCK_HFS 8
	20	.Os "Mac OS X"
	21	.Sh NAME
	22	.Nm fsck_hfs
	23	.Nd HFS file system consistency check
	24	.Sh SYNOPSIS
	25	.Nm fsck_hfs
	26	.Fl q
	27	.Op Fl df
	28	.Ar special ...
	29	.Nm fsck_hfs
	30	.Fl p
	31	.Op Fl df
	32	.Ar special ...
	33	.Nm fsck_hfs
	34	.Op Fl n \| y \| r
	35	.Op Fl dfgxlES
	36	.Op Fl D Ar flags
	37	.Op Fl b Ar size
	38	.Op Fl B Ar path
	39	.Op Fl m Ar mode
	40	.Op Fl c Ar size
	41	.Op Fl R Ar flags
	42	.Ar special ...
	43	.Sh DESCRIPTION
	44	.Pp
	45	The
	46	.Nm
	47	utility verifies and repairs standard HFS and HFS+ file systems.
	48	.Pp
	49	The first form of
	50	.Nm
	51	quickly checks the specified file systems to determine whether
	52	they were cleanly unmounted.
	53	.Pp
	54	The second form of
	55	.Nm
	56	preens the specified file systems.
	57	It is normally started by
	58	.Xr fsck 8
	59	run from
	60	.Pa /etc/rc.boot
	61	during automatic reboot, when a HFS file system is detected.
	62	When preening file systems,
	63	.Nm
	64	will fix common inconsistencies for file systems that were not
65	unmounted cleanly.
66	If more serious problems are found,
67	.Nm
68	does not try to fix them, indicates that it was not
69	successful, and exits.
70	.Pp
71	The third form of
72	.Nm
73	checks the specified file systems and tries to repair all
74	detected inconsistencies.
75	.Pp
76	If no options are specified
77	.Nm
78	will always check and attempt to fix the specified file systems.
79	.Pp
80	The options are as follows:
81	.Bl -hang -offset indent
82	.It Fl c Ar size
83	Specify the
84	.Ar size
85	of the cache used by
86	.Nm
87	internally. Bigger
88	.Ar size
89	can result in better performance but can result in deadlock when
90	used with
91	.Fl l
92	option. Size can be specified as a decimal, octal, or
93	hexadecimal number. If the number ends with a ``k'', ``m'',
94	or ``g'', the number is multiplied by 1024 (1K), 1048576 (1M),
95	or 1073741824 (1G), respectively.
96	.It Fl d
97	Display debugging information.
98	This option may provide useful information when
99	.Nm
100	cannot repair a damaged file system.
101	.It Fl D Ar flags
102	Print extra debugging information. The
103	.Ar flags
104	are a bitmap that control which kind of debug information is printed.
105	The following values are currently implemented:
106	.Bl -hang -offset indent -compact
107	.It 0x0001
108	Informational messages
109	.It 0x0002
110	Error messages
111	.It 0x0010
112	Extended attributes related messages
113	.It 0x0020
114	Overlapped extents related messages
115	.El
116	.It Fl b Ar size
117	Specify the size, in bytes, of the physical blocks used by the
118	.Fl B
119	option.
120	.It Fl B Ar path
121	Print the files containing the physical blocks listed in the file
122	.Ar path .
123	The file should contain one or more decimal, octal (with leading 0) or
124	hexadecimal (with leading 0x) numbers separated by white space. The physical
125	block numbers are relative to the start of the partition, so if you
126	have block numbers relative to the start of the device, you will have to
127	subtract the block number of the start of the partition. The size of a
128	physical block is given with the
129	.Fl b
130	option; the default is 512 bytes per block.
131	.It Fl f
132	When used with the
133	.Fl p
134	option, force
135	.Nm
136	to check `clean' file systems, otherwise it means force
137	.Nm
138	to check and repair journaled HFS+ file systems.
139	.It Fl g
140	Causes
141	.Nm
142	to generate its output strings in GUI format.
143	This option is used when another application with a graphical user interface
144	(like Mac OS X Disk Utility) is invoking the
145	.Nm
146	tool.
147	.It Fl x
148	Causes
149	.Nm
150	to generate its output strings in XML (plist) format. This option
151	implies the
152	.Fl g
153	option.
154	.It Fl l
155	Lock down the file system and perform a test-only check.
156	This makes it possible to check a file system that is currently mounted,
157	although no repairs can be made.
158	.It Fl m Ar mode
159	Mode is an octal number that will be used to set the permissions for the
160	lost+found directory when it is created.
161	The lost+found directory is only created when a volume is repaired and orphaned
162	files or directories are detected.
163	.Nm
164	places orphaned files and directories into the lost+found directory (located
165	at the root of the volume).
166	The default mode is 01777.
167	.It Fl p
168	Preen the specified file systems.
169	.It Fl q
170	Causes
171	.Nm
172	to quickly check whether the volume was unmounted cleanly.
173	If the volume was unmounted cleanly, then the exit status is 0.
174	If the volume was not unmounted cleanly, then the exit status will be non-zero.
175	In either case, a message is printed to standard output describing whether the
176	volume was clean or dirty.
177	.It Fl y
178	Always attempt to repair any damage that is found.
179	.It Fl n
180	Never attempt to repair any damage that is found.
181	.It Fl E
182	Cause
183	.Nm
184	to exit (with a value of 47) if it encounters any
185	major errors. A ``major error'' is considered one which
186	would impact using the volume in normal usage; an inconsistency
187	which would not impact such use is considered ``minor'' for this
188	option. Only valid with the
189	.Fl n
190	option.
191	.It Fl S
192	Cause
193	.Nm
194	to scan the entire device looking for I/O errors. It will
195	attempt to map the blocks with errors to names, similar to
196	the
197	.Fl B
198	option.
199	.It Fl R Ar flags
200	Rebuilds the requested btree. The following flags are supported:
201	.Bl -hang -offset indent -compact
202	.It a
203	Attribute btree
204	.It c
205	Catalog btree
206	.It e
207	Extents overflow btree
208	.El
209	Rebuilding a btree will only
210	work if there is enough free space on the file system for the new btree
211	file, and if
212	.Nm
213	is able to traverse each of the nodes in the requested btree successfully.
214	Rebuilding btrees is not supported on HFS Standard volumes.
215	.It Fl r
216	Rebuild the catalog btree. This is synonymous with
217	.Fl Rc .
218	.El
219	.Pp
220	Because of inconsistencies between the block device and the buffer cache,
221	the raw device should always be used.
222	.Sh EXIT VALUES
223	.Nm
224	indicates some status by exit value. The current list of exit status results
225	is:
226	.Bl -hang -offset indent -compact
227	.It 0
228	No errors found, or successfully repaired.
229	.It 3
230	A quick-check (the
231	.Fl n
232	option) found a dirty filesystem; no repairs were made.
233	.It 4
234	During boot, the root filesystem was found to be dirty; repairs were
235	made, and the filesystem was remounted. The system should be rebooted.
236	.It 8
237	A corrupt filesystem was found during a check, or repairs did not succeed.
238	.It 47
239	A major error was found with
240	.Fl E .
241	.El
242	.Sh SEE ALSO
243	.Xr fsck 8
244	.Sh BUGS
245	.Nm
246	is not able to fix some inconsistencies that it detects.
247	.Sh HISTORY
248	The
249	.Nm
250	command appeared in Mac OS X Server 1.0 .