Lab 7 — Settings and props

Android has two configuration systems that look similar from the shell and are completely different underneath. Knowing which one a value lives in saves an enormous amount of time.

TL;DR#

• Settings are three SQLite-backed namespaces: global, secure and system. Read and write them with settings get/put.
• Properties are a key-value store inherited from init, read with getprop and written with setprop. Most are read-only after boot.
• Settings values are per-user (mostly); properties are global to the device.
• settings put is reversible if you read the old value first. Some values take effect immediately, others need a reboot or a service restart.
• setprop on a ro. property fails by design: read-only properties cannot be changed at runtime.

Mental model#

Think of a car's dashboard and its engine control unit.

The dashboard is Settings: user-visible knobs that change behaviour and are meant to be adjusted. There are three panels — global, secure and system — with different access rules.

The ECU is properties: engineer-set values that describe the machine at boot, mostly fixed, and read by every component.

You can turn the dashboard knobs freely. You can read the ECU but you should not write to it, and some values are burned in.

Where the analogy breaks#

A dashboard knob usually maps to one behaviour. A single settings key can be read by many components and mean different things, and a property can be read by anything at all with no registry. Neither system has a schema, which is why reading unknown keys requires reading the code that consumes them.

Deep dive#

The three settings namespaces#

adb shell settings list global
adb shell settings list secure
adb shell settings list system

The namespaces differ by who can write them and what they hold:

The permission boundary is the reason secure exists: a value there is not readable by an ordinary app even though the setting is about that user.

Read one:

adb shell settings get global airplane_mode_on

The output is a string, or null if unset. Settings do not have types; the consumer interprets the string.

Changing a setting safely#

The safe pattern is read, write, verify, restore:

adb shell settings get system screen_off_timeout
adb shell settings put system screen_off_timeout 60000
adb shell settings get system screen_off_timeout
adb shell settings put system screen_off_timeout <old value>

Two cautions. First, a settings change can be picked up immediately by a listener, or only at the next read, depending on the consumer. Second, some settings are watched by system services and a bad value can make the device hard to use — screen_off_timeout of 0, for example.

Properties#

adb shell getprop

This prints hundreds of key-value pairs. The ones you will use:

• ro.build.version.sdk — the API level.
• ro.build.version.release — the Android version.
• ro.product.model — the model.
• ro.debuggable — whether the build is debuggable.
• ro.build.version.security_patch — the patch level.

Read one directly:

adb shell getprop ro.build.version.sdk

Write one:

adb shell setprop debug.example.value 1

A debug. property is writable by shell on a debuggable build. A ro. property is read-only: the ro. prefix means "read-only", set once at boot from the build or by init, and setprop will fail.

Which system is it?#

A quick decision procedure:

• If the value is a user preference that appears in Settings, it is probably a settings key.
• If the value is fixed at boot or describes the build, it is a property.
• If the value changes while the device runs and a system service consumes it, it could be either; check both.

A useful example is the screen timeout: it is a settings key because the user changes it. The API level is a property because it is a property of the build. Neither is a public API for apps.

Reading the consumers#

Because neither system has a schema, the way to know what a key does is to find what reads it. On a device, dumpsys output sometimes names the key; in the source, a search for the string finds the consumer. That is the same method as the AOSP tour: find the reader, not the definition.

Walkthrough#

1. Count the settings

   adb shell settings list global | wc -l adb shell settings list secure | wc -l adb shell settings list system | wc -l

   You should seeThree numbers, one per namespace.
2. Read a known setting

   adb shell settings get system screen_off_timeout

   You should seeA string value.
3. Read a known property

   adb shell getprop ro.build.version.sdk

   You should seeThe API level.
4. List debug properties

   adb shell getprop | grep debug

   You should seeA short list, or none on a release build.
5. Prove a ro property is read-only

   adb shell setprop ro.build.version.sdk 99}

   You should seeA failure message.

$ adb shell settings list global | wc -l
adb shell settings list secure | wc -l
adb shell settings list system | wc -l
adb shell settings get system screen_off_timeout
adb shell getprop ro.build.version.sdk
adb shell getprop | grep debug
adb shell setprop ro.build.version.sdk 99

Illustrative output — values differ per device.

Challenges#

Challenge 1 — Classify three values#

Decide whether each of these is a setting or a property: the device model, the font scale, the security patch level.

Challenge 2 — Change a setting and restore it#

Change the screen timeout, verify the change, then restore the original value.

adb shell settings get system screen_off_timeout
adb shell settings put system screen_off_timeout 60000
adb shell settings get system screen_off_timeout
adb shell settings put system screen_off_timeout <old>

Challenge 3 — Find who reads a property#

Pick a debug. property and find the component that reads it.

grep -rn "debug.example.value" frameworks/ system/

What you learned#

You can tell the two configuration systems apart, read both, and change one with a known undo. That covers a large fraction of "why is this device behaving like that?" questions.

Next#

Lab 8 — Intents uses the shell to exercise the component model.

Sources#