1page.title=Traditional Storage
2@jd:body
3<!--
4    Copyright 2015 The Android Open Source Project
5    Licensed under the Apache License, Version 2.0 (the "License");
6    you may not use this file except in compliance with the License.
7    You may obtain a copy of the License at
8        http://www.apache.org/licenses/LICENSE-2.0
9    Unless required by applicable law or agreed to in writing, software
10    distributed under the License is distributed on an "AS IS" BASIS,
11    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12    See the License for the specific language governing permissions and
13    limitations under the License.
14-->
15<div id="qv-wrapper">
16  <div id="qv">
17    <h2>In this document</h2>
18    <ol id="auto-toc">
19    </ol>
20  </div>
21</div>
22
23<img style="float: right; margin: 0px 15px 15px 15px;" src="images/ape_fwk_hal_extstor.png" alt="Android external storage HAL icon"/>
24
25<p>Android supports devices with traditional storage, which is defined to be a
26case-insensitive filesystem with immutable POSIX permission classes and modes.
27The notion of traditional storage encompasses emulated and portable storage.
28Portable storage is defined as any external storage that is not <a href="{@docRoot}devices/storage/adoptable.html">
29adopted</a> by the
30system and therefore not formatted and encrypted or tied to a specific device.
31Because traditional external storage offers minimal protection for stored data,
32system code should not store sensitive data on external storage. Specifically,
33configuration and log files should only be stored on internal storage where
34they can be effectively protected.</p>
35
36<h2 id="multi-user-external-storage">Multi-user external storage</h2>
37<p>Starting in Android 4.2, devices can support multiple users, and external
38storage must meet the following constraints:</p>
39<ul>
40<li>Each user must have their own isolated primary external storage, and
41must not have access to the primary external storage of other users.</li>
42<li>The <code>/sdcard</code> path must resolve to the correct user-specific
43primary external storage based on the user a process is running as.</li>
44<li>Storage for large OBB files in the <code>Android/obb</code> directory
45may be shared between multiple users as an optimization.</li>
46<li>Secondary external storage must not be writable by apps, except in
47package-specific directories as allowed by synthesized permissions.</li>
48</ul>
49<p>The default platform implementation of this feature leverages Linux kernel
50namespaces to create isolated mount tables for each Zygote-forked process,
51and then uses bind mounts to offer the correct user-specific primary external
52storage into that private namespace.</p>
53<p>At boot, the system mounts a single emulated external storage FUSE daemon
54at <code>EMULATED_STORAGE_SOURCE</code>, which is hidden from apps. After
55the Zygote forks, it bind mounts the appropriate user-specific subdirectory
56from under the FUSE daemon to <code>EMULATED_STORAGE_TARGET</code> so that
57external storage paths resolve correctly for the app. Because an app lacks
58accessible mount points for other users' storage, they can only access
59storage for the user it was started as.</p>
60<p>This implementation also uses the shared subtree kernel feature to
61propagate mount events from the default root namespace into app namespaces,
62which ensures that features like ASEC containers and OBB mounting continue
63working correctly. It does this by mounting the rootfs as shared, and then
64remounting it as slave after each Zygote namespace is created.</p>
65
66<h2 id="multiple-external-storage-devices">Multiple external storage devices</h2>
67<p>Starting in Android 4.4, multiple external storage devices are surfaced
68to developers through <code>Context.getExternalFilesDirs()</code>,
69<code>Context.getExternalCacheDirs()</code>, and
70<code>Context.getObbDirs()</code>.</p>
71</p>External storage devices surfaced through these APIs must be a
72semi-permanent part of the device (such as an SD card slot in a battery
73compartment). Developers expect data stored in these locations to be
74available over long periods of time. For this reason, transient storage
75devices (such as USB mass storage drives) should not be surfaced through
76these APIs.</p>
77<p>The <code>WRITE_EXTERNAL_STORAGE</code> permission must only grant write
78access to the primary external storage on a device. Apps must not be
79allowed to write to secondary external storage devices, except in their
80package-specific directories as allowed by synthesized
81permissions. Restricting writes in this way ensures the system can clean
82up files when applications are uninstalled.</p>
83
84<h2 id=support_usb_media>USB media support</h2>
85
86<p>Android 6.0 supports portable storage devices which are only connected to the
87device for a short period of time, like USB flash drives. When a user inserts a
88new portable device, the platform shows a notification to let them copy or
89manage the contents of that device.</p>
90
91<p>In Android 6.0, any device that is not adopted is considered portable. Because
92portable storage is connected for only a short time, the platform avoids heavy
93operations such as media scanning. Third-party apps must go through the <a href="https://developer.android.com/guide/topics/providers/document-provider.html">Storage Access Framework</a> to interact with files on portable storage; direct access is explicitly
94blocked for privacy and security reasons.</p>
95