1page.title=External Storage
2@jd:body
3
4<!--
5    Copyright 2014 The Android Open Source Project
6
7    Licensed under the Apache License, Version 2.0 (the "License");
8    you may not use this file except in compliance with the License.
9    You may obtain a copy of the License at
10
11        http://www.apache.org/licenses/LICENSE-2.0
12
13    Unless required by applicable law or agreed to in writing, software
14    distributed under the License is distributed on an "AS IS" BASIS,
15    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16    See the License for the specific language governing permissions and
17    limitations under the License.
18-->
19
20
21<p>Android supports devices with external storage, which is defined to be a
22case-insensitive filesystem with immutable POSIX permission classes and
23modes. External storage can be provided by physical media (such as an SD
24card), or by exposing a portion of internal storage through an emulation
25layer. Devices may contain multiple instances of external storage.</p>
26
27<p>Access to external storage is protected by various Android
28permissions. Starting in Android 1.0, write access is protected with the
29<code>WRITE_EXTERNAL_STORAGE</code> permission. Starting in Android 4.1,
30read access is protected with the <code>READ_EXTERNAL_STORAGE</code>
31permission.</p>
32
33<p>Starting in Android 4.4, the owner, group and modes of files on external
34storage devices are now synthesized based on directory structure. This
35enables apps to manage their package-specific directories on external
36storage without requiring they hold the broad
37<code>WRITE_EXTERNAL_STORAGE</code> permission. For example, the app with
38package name <code>com.example.foo</code> can now freely access
39<code>Android/data/com.example.foo/</code> on external storage devices with
40no permissions. These synthesized permissions are accomplished by wrapping
41raw storage devices in a FUSE daemon.</p>
42
43<p>Since external storage offers minimal protection for stored data, system
44code should not store sensitive data on external storage. Specifically,
45configuration and log files should only be stored on internal storage where
46they can be effectively protected.</p>
47
48
49<h2 id="multiple-external-storage-devices">Multiple external storage devices</h2>
50
51<p>Starting in Android 4.4, multiple external storage devices are surfaced
52to developers through <code>Context.getExternalFilesDirs()</code>,
53<code>Context.getExternalCacheDirs()</code>, and
54<code>Context.getObbDirs()</code>.</p>
55
56</p>External storage devices surfaced through these APIs must be a
57semi-permanent part of the device (such as an SD card slot in a battery
58compartment). Developers expect data stored in these locations to be
59available over long periods of time. For this reason, transient storage
60devices (such as USB mass storage drives) should not be surfaced through
61these APIs.</p>
62
63<p>The <code>WRITE_EXTERNAL_STORAGE</code> permission must only grant write
64access to the primary external storage on a device. Apps must not be
65allowed to write to secondary external storage devices, except in their
66package-specific directories as allowed by synthesized
67permissions. Restricting writes in this way ensures the system can clean
68up files when applications are uninstalled.</p>
69
70
71<h2 id="multi-user-external-storage">Multi-user external storage</h2>
72
73<p>Starting in Android 4.2, devices can support multiple users, and external
74storage must meet the following constraints:</p>
75
76<ul>
77<li>Each user must have their own isolated primary external storage, and
78must not have access to the primary external storage of other users.</li>
79<li>The <code>/sdcard</code> path must resolve to the correct user-specific
80primary external storage based on the user a process is running as.</li>
81<li>Storage for large OBB files in the <code>Android/obb</code> directory
82may be shared between multiple users as an optimization.</li>
83<li>Secondary external storage must not be writable by apps, except in
84package-specific directories as allowed by synthesized permissions.</li>
85</ul>
86
87<p>The default platform implementation of this feature leverages Linux kernel
88namespaces to create isolated mount tables for each Zygote-forked process,
89and then uses bind mounts to offer the correct user-specific primary external
90storage into that private namespace.</p>
91
92<p>At boot, the system mounts a single emulated external storage FUSE daemon
93at <code>EMULATED_STORAGE_SOURCE</code>, which is hidden from apps. After
94the Zygote forks, it bind mounts the appropriate user-specific subdirectory
95from under the FUSE daemon to <code>EMULATED_STORAGE_TARGET</code> so that
96external storage paths resolve correctly for the app. Because an app lacks
97accessible mount points for other users' storage, they can only access
98storage for the user it was started as.</p>
99
100<p>This implementation also uses the shared subtree kernel feature to
101propagate mount events from the default root namespace into app namespaces,
102which ensures that features like ASEC containers and OBB mounting continue
103working correctly. It does this by mounting the rootfs as shared, and then
104remounting it as slave after each Zygote namespace is created.</p>
105