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:

1. Location-based purging (implicit priority):

   • tmp/ → Purged aggressively (anytime)
   • Library/Caches/ → Purged under storage pressure
   • Documents/, Application Support/ → Never purged

2. Capacity checking (explicit strategy):

   • volumeAvailableCapacityForImportantUsage — For must-save data
   • volumeAvailableCapacityForOpportunisticUsage — For nice-to-have data
   • Check before saving, choose location based on available space

URL Resource Values for Storage

Complete Reference Table

Checking Available Space (Modern Approach)

// ✅ CORRECT: Check appropriate capacity before saving
func checkSpaceBeforeSaving(fileSize: Int64, isEssential: Bool) -> Bool {
    let homeURL = FileManager.default.homeDirectoryForCurrentUser

    do {
        let values = try homeURL.resourceValues(forKeys: [
            .volumeAvailableCapacityForImportantUsageKey,
            .volumeAvailableCapacityForOpportunisticUsageKey
        ])

        if isEssential {
            // For must-save data (user-created content, critical app data)
            let importantCapacity = values.volumeAvailableCapacityForImportantUsage ?? 0
            return fileSize < importantCapacity
        } else {
            // For nice-to-have data (caches, thumbnails)
            let opportunisticCapacity = values.volumeAvailableCapacityForOpportunisticUsage ?? 0
            return fileSize < opportunisticCapacity
        }
    } catch {
        print("Error checking capacity: \(error)")
        return false
    }
}

// Usage
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"

// ✅ CORRECT: Different thresholds for different data types
func shouldDownloadThumbnail(size: Int64) -> Bool {
    let capacity = try? FileManager.default.homeDirectoryForCurrentUser
        .resourceValues(forKeys: [.volumeAvailableCapacityForOpportunisticUsageKey])
        .volumeAvailableCapacityForOpportunisticUsage ?? 0

    // Only download optional content if there's plenty of space
    return size < capacity
}

func canSaveUserDocument(size: Int64) -> Bool {
    let capacity = try? FileManager.default.homeDirectoryForCurrentUser
        .resourceValues(forKeys: [.volumeAvailableCapacityForImportantUsageKey])
        .volumeAvailableCapacityForImportantUsage ?? 0

    // User documents are essential
    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.

// ✅ CORRECT: Exclude large re-downloadable files from backup
func markExcludedFromBackup(url: URL) throws {
    var resourceValues = URLResourceValues()
    resourceValues.isExcludedFromBackup = true
    try url.setResourceValues(resourceValues)
}

// Example: Downloaded podcast episodes
func downloadPodcast(url: URL) throws {
    let appSupportURL = FileManager.default.urls(
        for: .applicationSupportDirectory,
        in: .userDomainMask
    )[0]

    let podcastURL = appSupportURL
        .appendingPathComponent("Podcasts")
        .appendingPathComponent(url.lastPathComponent)

    // Download file
    let data = try Data(contentsOf: url)
    try data.write(to: podcastURL)

    // Mark as excluded from backup (can re-download)
    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

// ✅ Check if file is excluded from backup
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.

// ✅ CORRECT: Mark cache files as purgeable
func markAsPurgeable(url: URL) throws {
    var resourceValues = URLResourceValues()
    resourceValues.isPurgeable = true
    try url.setResourceValues(resourceValues)
}

// Example: Thumbnail cache
func cacheThumbnail(image: UIImage, for url: URL) throws {
    let cacheURL = FileManager.default.urls(
        for: .cachesDirectory,
        in: .userDomainMask
    )[0]

    let thumbnailURL = cacheURL.appendingPathComponent(url.