iOS Storage Management Reference
Purpose: Comprehensive reference for storage pressure, purging policies, disk space, and URL resource values
Availability: iOS 5.0+ (basic), iOS 11.0+ (modern capacity APIs)
Context: Answer to "Does iOS provide any way to mark files as 'purge as last resort'?"
When to Use This Skill
Use this skill when you need to:
- Understand iOS file purging behavior
- Check available disk space correctly
- Set purge priorities for cached files
- Exclude files from backup
- Monitor storage pressure
- Mark files as purgeable
- Understand volume capacity APIs
- Handle "low storage" scenarios
The Core Question
"Does iOS provide any way to mark files as 'purge as last resort'?"
Answer: Not directly, but iOS provides two approaches:
-
Location-based purging (implicit priority):
tmp/ → Purged aggressively (anytime)Library/Caches/ → Purged under storage pressureDocuments/, Application Support/ → Never purged
-
Capacity checking (explicit strategy):
volumeAvailableCapacityForImportantUsage — For must-save datavolumeAvailableCapacityForOpportunisticUsage — For nice-to-have data- Check before saving, choose location based on available space
URL Resource Values for Storage
Complete Reference Table
| Resource Key |
Type |
Purpose |
Availability |
volumeAvailableCapacityKey |
Int64 |
Total available space |
iOS 5.0+ |
volumeAvailableCapacityForImportantUsageKey |
Int64 |
Space for essential files |
iOS 11.0+ |
volumeAvailableCapacityForOpportunisticUsageKey |
Int64 |
Space for optional files |
iOS 11.0+ |
volumeTotalCapacityKey |
Int64 |
Total volume capacity |
iOS 5.0+ |
isExcludedFromBackupKey |
Bool |
Exclude from iCloud/iTunes backup |
iOS 5.1+ |
isPurgeableKey |
Bool |
System can delete under pressure |
iOS 9.0+ |
fileAllocatedSizeKey |
Int64 |
Actual disk space used |
iOS 5.0+ |
totalFileAllocatedSizeKey |
Int64 |
Total allocated (including metadata) |
iOS 5.0+ |
Checking Available Space (Modern Approach)
func checkSpaceBeforeSaving(fileSize: Int64, isEssential: Bool) -> Bool {
let homeURL = FileManager.default.homeDirectoryForCurrentUser
do {
let values = try homeURL.resourceValues(forKeys: [
.volumeAvailableCapacityForImportantUsageKey,
.volumeAvailableCapacityForOpportunisticUsageKey
])
if isEssential {
let importantCapacity = values.volumeAvailableCapacityForImportantUsage ?? 0
return fileSize < importantCapacity
} else {
let opportunisticCapacity = values.volumeAvailableCapacityForOpportunisticUsage ?? 0
return fileSize < opportunisticCapacity
}
} catch {
print("Error checking capacity: \(error)")
return false
}
}
if checkSpaceBeforeSaving(fileSize: imageData.count, isEssential: true) {
try imageData.write(to: documentsURL.appendingPathComponent("photo.jpg"))
} else {
showLowStorageAlert()
}
Important vs Opportunistic Capacity
volumeAvailableCapacityForImportantUsage:
- Space reserved for essential operations
- Use for: User-created content, must-save data
- System reserves this space more aggressively
- Higher threshold
volumeAvailableCapacityForOpportunisticUsage:
- Space available for optional operations
- Use for: Caches, thumbnails, pre-fetching
- Lower threshold (system may already be under pressure)
- Indicates "go ahead if you want, but system is getting full"
func shouldDownloadThumbnail(size: Int64) -> Bool {
let capacity = try? FileManager.default.homeDirectoryForCurrentUser
.resourceValues(forKeys: [.volumeAvailableCapacityForOpportunisticUsageKey])
.volumeAvailableCapacityForOpportunisticUsage ?? 0
return size < capacity
}
func canSaveUserDocument(size: Int64) -> Bool {
let capacity = try? FileManager.default.homeDirectoryForCurrentUser
.resourceValues(forKeys: [.volumeAvailableCapacityForImportantUsageKey])
.volumeAvailableCapacityForImportantUsage ?? 0
return size < capacity
}
Backup Exclusion
isExcludedFromBackup
Files in Caches/ are automatically excluded from backup, but you should explicitly mark re-downloadable files in other directories.
func markExcludedFromBackup(url: URL) throws {
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true
try url.setResourceValues(resourceValues)
}
func downloadPodcast(url: URL) throws {
let appSupportURL = FileManager.default.urls(
for: .applicationSupportDirectory,
in: .userDomainMask
)[0]
let podcastURL = appSupportURL
.appendingPathComponent("Podcasts")
.appendingPathComponent(url.lastPathComponent)
let data = try Data(contentsOf: url)
try data.write(to: podcastURL)
try markExcludedFromBackup(url: podcastURL)
}
When to exclude from backup:
- ✅ Downloaded content that can be re-fetched
- ✅ Generated thumbnails
- ✅ Cached API responses
- ✅ Large media files from server
- ❌ User-created content (always back up)
- ❌ App data that can't be recreated
Checking Backup Status
func isExcludedFromBackup(url: URL) -> Bool {
let values = try? url.resourceValues(forKeys: [.isExcludedFromBackupKey])
return values?.isExcludedFromBackup ?? false
}
Purgeable Files
isPurgeable
Mark files as candidates for automatic purging by the system.
func markAsPurgeable(url: URL) throws {
var resourceValues = URLResourceValues()
resourceValues.isPurgeable = true
try url.setResourceValues(resourceValues)
}
func cacheThumbnail(image: UIImage, for url: URL) throws {
let cacheURL = FileManager.default.urls(
for: .cachesDirectory,
in: .userDomainMask
)[0]
let thumbnailURL = cacheURL.appendingPathComponent(url.
