53b89d0edc15d9230b5dca489d6e19fdf0ca0e0e
[muen/linux.git] / Documentation / filesystems / index.rst
1 =====================
2 Linux Filesystems API
3 =====================
4
5 The Linux VFS
6 =============
7
8 The Filesystem types
9 --------------------
10
11 .. kernel-doc:: include/linux/fs.h
12    :internal:
13
14 The Directory Cache
15 -------------------
16
17 .. kernel-doc:: fs/dcache.c
18    :export:
19
20 .. kernel-doc:: include/linux/dcache.h
21    :internal:
22
23 Inode Handling
24 --------------
25
26 .. kernel-doc:: fs/inode.c
27    :export:
28
29 .. kernel-doc:: fs/bad_inode.c
30    :export:
31
32 Registration and Superblocks
33 ----------------------------
34
35 .. kernel-doc:: fs/super.c
36    :export:
37
38 File Locks
39 ----------
40
41 .. kernel-doc:: fs/locks.c
42    :export:
43
44 .. kernel-doc:: fs/locks.c
45    :internal:
46
47 Other Functions
48 ---------------
49
50 .. kernel-doc:: fs/mpage.c
51    :export:
52
53 .. kernel-doc:: fs/namei.c
54    :export:
55
56 .. kernel-doc:: fs/buffer.c
57    :export:
58
59 .. kernel-doc:: block/bio.c
60    :export:
61
62 .. kernel-doc:: fs/seq_file.c
63    :export:
64
65 .. kernel-doc:: fs/filesystems.c
66    :export:
67
68 .. kernel-doc:: fs/fs-writeback.c
69    :export:
70
71 .. kernel-doc:: fs/block_dev.c
72    :export:
73
74 The proc filesystem
75 ===================
76
77 sysctl interface
78 ----------------
79
80 .. kernel-doc:: kernel/sysctl.c
81    :export:
82
83 proc filesystem interface
84 -------------------------
85
86 .. kernel-doc:: fs/proc/base.c
87    :internal:
88
89 Events based on file descriptors
90 ================================
91
92 .. kernel-doc:: fs/eventfd.c
93    :export:
94
95 The Filesystem for Exporting Kernel Objects
96 ===========================================
97
98 .. kernel-doc:: fs/sysfs/file.c
99    :export:
100
101 .. kernel-doc:: fs/sysfs/symlink.c
102    :export:
103
104 The debugfs filesystem
105 ======================
106
107 debugfs interface
108 -----------------
109
110 .. kernel-doc:: fs/debugfs/inode.c
111    :export:
112
113 .. kernel-doc:: fs/debugfs/file.c
114    :export:
115
116 The Linux Journalling API
117 =========================
118
119 Overview
120 --------
121
122 Details
123 ~~~~~~~
124
125 The journalling layer is easy to use. You need to first of all create a
126 journal_t data structure. There are two calls to do this dependent on
127 how you decide to allocate the physical media on which the journal
128 resides. The :c:func:`jbd2_journal_init_inode` call is for journals stored in
129 filesystem inodes, or the :c:func:`jbd2_journal_init_dev` call can be used
130 for journal stored on a raw device (in a continuous range of blocks). A
131 journal_t is a typedef for a struct pointer, so when you are finally
132 finished make sure you call :c:func:`jbd2_journal_destroy` on it to free up
133 any used kernel memory.
134
135 Once you have got your journal_t object you need to 'mount' or load the
136 journal file. The journalling layer expects the space for the journal
137 was already allocated and initialized properly by the userspace tools.
138 When loading the journal you must call :c:func:`jbd2_journal_load` to process
139 journal contents. If the client file system detects the journal contents
140 does not need to be processed (or even need not have valid contents), it
141 may call :c:func:`jbd2_journal_wipe` to clear the journal contents before
142 calling :c:func:`jbd2_journal_load`.
143
144 Note that jbd2_journal_wipe(..,0) calls
145 :c:func:`jbd2_journal_skip_recovery` for you if it detects any outstanding
146 transactions in the journal and similarly :c:func:`jbd2_journal_load` will
147 call :c:func:`jbd2_journal_recover` if necessary. I would advise reading
148 :c:func:`ext4_load_journal` in fs/ext4/super.c for examples on this stage.
149
150 Now you can go ahead and start modifying the underlying filesystem.
151 Almost.
152
153 You still need to actually journal your filesystem changes, this is done
154 by wrapping them into transactions. Additionally you also need to wrap
155 the modification of each of the buffers with calls to the journal layer,
156 so it knows what the modifications you are actually making are. To do
157 this use :c:func:`jbd2_journal_start` which returns a transaction handle.
158
159 :c:func:`jbd2_journal_start` and its counterpart :c:func:`jbd2_journal_stop`,
160 which indicates the end of a transaction are nestable calls, so you can
161 reenter a transaction if necessary, but remember you must call
162 :c:func:`jbd2_journal_stop` the same number of times as
163 :c:func:`jbd2_journal_start` before the transaction is completed (or more
164 accurately leaves the update phase). Ext4/VFS makes use of this feature to
165 simplify handling of inode dirtying, quota support, etc.
166
167 Inside each transaction you need to wrap the modifications to the
168 individual buffers (blocks). Before you start to modify a buffer you
169 need to call :c:func:`jbd2_journal_get_create_access()` /
170 :c:func:`jbd2_journal_get_write_access()` /
171 :c:func:`jbd2_journal_get_undo_access()` as appropriate, this allows the
172 journalling layer to copy the unmodified
173 data if it needs to. After all the buffer may be part of a previously
174 uncommitted transaction. At this point you are at last ready to modify a
175 buffer, and once you are have done so you need to call
176 :c:func:`jbd2_journal_dirty_metadata`. Or if you've asked for access to a
177 buffer you now know is now longer required to be pushed back on the
178 device you can call :c:func:`jbd2_journal_forget` in much the same way as you
179 might have used :c:func:`bforget` in the past.
180
181 A :c:func:`jbd2_journal_flush` may be called at any time to commit and
182 checkpoint all your transactions.
183
184 Then at umount time , in your :c:func:`put_super` you can then call
185 :c:func:`jbd2_journal_destroy` to clean up your in-core journal object.
186
187 Unfortunately there a couple of ways the journal layer can cause a
188 deadlock. The first thing to note is that each task can only have a
189 single outstanding transaction at any one time, remember nothing commits
190 until the outermost :c:func:`jbd2_journal_stop`. This means you must complete
191 the transaction at the end of each file/inode/address etc. operation you
192 perform, so that the journalling system isn't re-entered on another
193 journal. Since transactions can't be nested/batched across differing
194 journals, and another filesystem other than yours (say ext4) may be
195 modified in a later syscall.
196
197 The second case to bear in mind is that :c:func:`jbd2_journal_start` can block
198 if there isn't enough space in the journal for your transaction (based
199 on the passed nblocks param) - when it blocks it merely(!) needs to wait
200 for transactions to complete and be committed from other tasks, so
201 essentially we are waiting for :c:func:`jbd2_journal_stop`. So to avoid
202 deadlocks you must treat :c:func:`jbd2_journal_start` /
203 :c:func:`jbd2_journal_stop` as if they were semaphores and include them in
204 your semaphore ordering rules to prevent
205 deadlocks. Note that :c:func:`jbd2_journal_extend` has similar blocking
206 behaviour to :c:func:`jbd2_journal_start` so you can deadlock here just as
207 easily as on :c:func:`jbd2_journal_start`.
208
209 Try to reserve the right number of blocks the first time. ;-). This will
210 be the maximum number of blocks you are going to touch in this
211 transaction. I advise having a look at at least ext4_jbd.h to see the
212 basis on which ext4 uses to make these decisions.
213
214 Another wriggle to watch out for is your on-disk block allocation
215 strategy. Why? Because, if you do a delete, you need to ensure you
216 haven't reused any of the freed blocks until the transaction freeing
217 these blocks commits. If you reused these blocks and crash happens,
218 there is no way to restore the contents of the reallocated blocks at the
219 end of the last fully committed transaction. One simple way of doing
220 this is to mark blocks as free in internal in-memory block allocation
221 structures only after the transaction freeing them commits. Ext4 uses
222 journal commit callback for this purpose.
223
224 With journal commit callbacks you can ask the journalling layer to call
225 a callback function when the transaction is finally committed to disk,
226 so that you can do some of your own management. You ask the journalling
227 layer for calling the callback by simply setting
228 ``journal->j_commit_callback`` function pointer and that function is
229 called after each transaction commit. You can also use
230 ``transaction->t_private_list`` for attaching entries to a transaction
231 that need processing when the transaction commits.
232
233 JBD2 also provides a way to block all transaction updates via
234 :c:func:`jbd2_journal_lock_updates()` /
235 :c:func:`jbd2_journal_unlock_updates()`. Ext4 uses this when it wants a
236 window with a clean and stable fs for a moment. E.g.
237
238 ::
239
240
241         jbd2_journal_lock_updates() //stop new stuff happening..
242         jbd2_journal_flush()        // checkpoint everything.
243         ..do stuff on stable fs
244         jbd2_journal_unlock_updates() // carry on with filesystem use.
245
246 The opportunities for abuse and DOS attacks with this should be obvious,
247 if you allow unprivileged userspace to trigger codepaths containing
248 these calls.
249
250 Summary
251 ~~~~~~~
252
253 Using the journal is a matter of wrapping the different context changes,
254 being each mount, each modification (transaction) and each changed
255 buffer to tell the journalling layer about them.
256
257 Data Types
258 ----------
259
260 The journalling layer uses typedefs to 'hide' the concrete definitions
261 of the structures used. As a client of the JBD2 layer you can just rely
262 on the using the pointer as a magic cookie of some sort. Obviously the
263 hiding is not enforced as this is 'C'.
264
265 Structures
266 ~~~~~~~~~~
267
268 .. kernel-doc:: include/linux/jbd2.h
269    :internal:
270
271 Functions
272 ---------
273
274 The functions here are split into two groups those that affect a journal
275 as a whole, and those which are used to manage transactions
276
277 Journal Level
278 ~~~~~~~~~~~~~
279
280 .. kernel-doc:: fs/jbd2/journal.c
281    :export:
282
283 .. kernel-doc:: fs/jbd2/recovery.c
284    :internal:
285
286 Transasction Level
287 ~~~~~~~~~~~~~~~~~~
288
289 .. kernel-doc:: fs/jbd2/transaction.c
290
291 See also
292 --------
293
294 `Journaling the Linux ext2fs Filesystem, LinuxExpo 98, Stephen
295 Tweedie <http://kernel.org/pub/linux/kernel/people/sct/ext3/journal-design.ps.gz>`__
296
297 `Ext3 Journalling FileSystem, OLS 2000, Dr. Stephen
298 Tweedie <http://olstrans.sourceforge.net/release/OLS2000-ext3/OLS2000-ext3.html>`__
299
300 splice API
301 ==========
302
303 splice is a method for moving blocks of data around inside the kernel,
304 without continually transferring them between the kernel and user space.
305
306 .. kernel-doc:: fs/splice.c
307
308 pipes API
309 =========
310
311 Pipe interfaces are all for in-kernel (builtin image) use. They are not
312 exported for use by modules.
313
314 .. kernel-doc:: include/linux/pipe_fs_i.h
315    :internal:
316
317 .. kernel-doc:: fs/pipe.c
318
319 Encryption API
320 ==============
321
322 A library which filesystems can hook into to support transparent
323 encryption of files and directories.
324
325 .. toctree::
326     :maxdepth: 2
327
328     fscrypt