Como ler e editar arquivos plist

Saber ler e editar um arquivo plist é trabalhar com o formato de configuração da Apple — os arquivos de chave-valor que movem o macOS e o iOS em silêncio. Cada app traz um Info.plist, cada tarefa agendada em segundo plano é um plist do launchd, cada perfil de provisionamento e cada perfil de dispositivo .mobileconfig é um plist por baixo. O formato em si é simples: dicionários, arrays, strings, números, booleanos, datas e dados binários, aninhados o quanto você quiser. O problema começa porque o mesmo formato é distribuído com dois disfarces — XML legível para humanos, e uma forma binária compacta que parece lixo num editor de texto — e porque um único tipo errado pode impedir silenciosamente que uma tarefa seja executada. Você pode colar qualquer plist no Plist Workbench e lê-lo, editá-lo, convertê-lo e validá-lo no seu navegador — nada é enviado — mas este artigo ensina você a ler os arquivos sozinho, para que a árvore nunca seja uma caixa-preta.

O que é um plist — e os quatro disfarces que ele usa

Uma lista de propriedades, ou plist, é a forma da Apple de guardar configuração estruturada: uma árvore de dicionários e arrays cujas folhas são strings, inteiros, números reais, booleanos, datas e blocos de dados binários. É a mesma ideia de um objeto JSON ou de um arquivo YAML, mas é anterior a ambos nas plataformas da Apple e está embutida no sistema operacional — o macOS e o iOS leem plists o tempo todo, sem nunca perguntar a você. Se você já se perguntou onde um app guarda seu bundle ID, sua versão ou as permissões que pede, a resposta é um plist, e ele esteve à vista o tempo todo.

O mesmo formato aparece em quatro lugares que parecem não ter relação até você conhecer o truque. Dentro de cada pacote de app, o Info.plist declara a identidade do app: seu bundle ID, versão, tipos de documento suportados e as permissões que solicita. Em ~/Library/LaunchAgents e /Library/LaunchDaemons, os arquivos de tarefas do launchd descrevem tarefas em segundo plano: o que executar, quando e em que condições. Um perfil de provisionamento .mobileprovision é um plist (envolvido numa assinatura CMS) que lista quais dispositivos e permissões um app pode usar. E um perfil de dispositivo .mobileconfig é um plist que descreve o Wi-Fi, a VPN, os certificados e as restrições a instalar num dispositivo. O mesmo formato, quatro disfarces — aprenda a ler um e você saberá ler os quatro.

Binário vs XML: a mágica bplist00, e por que editar um plist binário à mão o corrompe

Um plist tem duas serializações. A forma XML começa com <?xml e <plist version="1.0">, e pode ser lida em qualquer editor de texto: as chaves em tags <key>, os valores em <string>, <integer>, <true/>, <array> e <dict>. A forma binária é uma codificação compacta que começa com os oito bytes mágicos bplist00, seguidos de uma tabela de objetos, uma tabela de offsets e um trailer que registra onde cada coisa mora. Plists binários são menores e o sistema os carrega mais rápido, e é por isso que a maioria dos plists de um Mac de verdade é binária — e por isso abrir um deles num editor de texto mostra lixo.

Como saber qual você tem: olhe os primeiros bytes. bplist00 significa binário; <?xml ou <plist significa XML. E aqui está a regra que salva arquivos: nunca edite os bytes binários à mão. Um plist binário é uma teia de offsets — mude uma string para uma mais longa e todos os offsets depois dela ficam errados, o trailer deixa de bater com a tabela e o arquivo fica corrompido, mesmo que o texto que você mudou pareça certo. O caminho seguro é sempre o mesmo: converter de binário para XML, editar o XML, converter de volta para binário e reanalisar o resultado para provar que ele continua válido. Num Mac, isso é plutil -convert xml1 e plutil -convert binary1; no navegador, o Plist Workbench faz a mesma viagem de ida e volta por você.

Lendo uma tarefa do launchd à mão: Label, ProgramArguments, RunAtLoad, KeepAlive, StartCalendarInterval

Uma tarefa do launchd é um plist com um vocabulário pequeno, e você pode ler uma em menos de um minuto quando conhece as chaves. Label é o nome único da tarefa, convencionalmente um domínio reverso como com.example.backup — o launchd o usa para identificar a tarefa, e duas tarefas com o mesmo rótulo colidem. ProgramArguments é um array de strings: o programa a executar seguido de seus argumentos, de modo que ["/usr/local/bin/backup.sh"] executa esse script sem argumentos. RunAtLoad é um booleano: true significa executar a tarefa assim que ela for carregada. KeepAlive, também booleano, significa reiniciá-la sempre que ela terminar. Essas quatro chaves descrevem a maioria das tarefas que você vai encontrar.

A chave de agendamento é StartCalendarInterval, um dicionário de campos de calendário — Minute, Hour, Day, Weekday, Month — qualquer um dos quais você pode omitir, de modo que {Hour: 3, Minute: 30} significa todos os dias às 03:30. Sua prima mais simples, StartInterval, é um único inteiro: executar a cada N segundos. A amostra no bloco de código abaixo é uma tarefa completa e funcional nessa forma — Label, ProgramArguments, RunAtLoad, StartCalendarInterval — e vale a pena lê-la linha por linha, porque cada tarefa do launchd que você encontrar é uma variação dela: as mesmas chaves, valores diferentes, e um extra ocasional como WorkingDirectory ou StandardOutPath para indicar para onde vai a saída.

As chaves que quebram as coisas: erros de tipo, contêineres errados, números fora do intervalo

A maioria das tarefas do launchd quebradas não se quebra por erros de digitação — se quebra por tipos. O launchd espera que ProgramArguments seja um array de strings; entregue uma única string e a tarefa não carrega, com um erro que diz muito pouco. KeepAlive, RunAtLoad e Disabled precisam ser booleanos, não as strings "true" e "false" — uma string que soletra "true" não é true, e o launchd a tratará como erro de tipo. StartInterval precisa ser um inteiro positivo; zero ou número negativo não faz sentido e é rejeitado. Esses são os erros que um editor de texto nunca detecta, porque o XML está perfeitamente bem formado — só o significado está errado.

A segunda família de quebras são os números fora do seu intervalo. Em StartCalendarInterval, Minute precisa ser 0–59, Hour 0–23, Weekday 0–7, Day 1–31 e Month 1–12 — um Hour de 25 não significa "amanhã à 1h", significa que a tarefa nunca executa, e o launchd pode nem dizer por quê. A terceira família é o par que não deve aparecer junto: Program e ProgramArguments são duas formas de dizer a mesma coisa, e dar as duas é ambíguo — escolha uma, e prefira ProgramArguments, que é a forma que a Apple documenta. Um validador que verifica tipos, intervalos e esses conflitos detecta as três famílias antes que a tarefa chegue ao launchd, que é exatamente o que as verificações de launchd do workbench fazem.

Editando com segurança: backup, converter, editar, converter de volta, verificar

Editar um plist com segurança é um ritual de cinco passos, e a ordem importa. Primeiro, faça backup do arquivo original — copie-o para outro lugar antes de tocá-lo, porque uma tarefa do launchd ou um perfil de dispositivo não tem botão de desfazer. Segundo, se o arquivo for binário, converta-o para XML; nunca edite os bytes binários diretamente, pelas razões de offset acima. Terceiro, faça a edição no XML: mude um valor, renomeie uma chave, adicione um item ao array — e mantenha os tipos certos, uma string onde vai uma string, um array onde vai um array. Quarto, converta de volta para binário se o original era binário, para que o arquivo volte na forma que o sistema espera.

Quinto, e o passo mais ignorado: verifique reanalisando. Rode plutil -lint no resultado, ou cole-o no workbench e veja-o ser analisado sem erros — se o arquivo for reanalisado e os valores que voltaram forem os que você queria, a edição funcionou. Se ele não for analisado, você ainda tem o backup do passo um, e o arquivo no disco nunca foi tocado pelo editor: o workbench edita uma cópia em memória e só escreve um arquivo quando você exporta explicitamente. Essa última propriedade é todo o sentido de editar no navegador — o original fica intacto até você decidir que a nova versão é boa.

O que o Plist Workbench faz — e o que ele não faz

O workbench analisa as duas formas de plist — binário bplist00 e XML — numa árvore que você pode expandir, buscar por caminho (como StartCalendarInterval.Hour) e editar no lugar: mudar um escalar, renomear uma chave, adicionar ou remover chaves e itens de array, e mudar o tipo de um valor quando isso não for ambíguo. Cada exportação — plist XML, plist binário, JSON ou um CSV da tabela de caminhos achatada — reflete o modelo editado, não o arquivo original. Quando o plist parece uma tarefa do launchd, ele executa as verificações semânticas das seções anteriores: Label presente, exatamente um de Program e ProgramArguments, campos de calendário dentro do intervalo, booleanos que realmente são booleanos. Esse é todo o trabalho, e tudo acontece no seu navegador: o arquivo nunca sai do seu dispositivo.

O que ele não faz é igualmente importante. Ele não instala nada — não vai carregar sua tarefa no launchd, instalar um .mobileconfig num dispositivo ou provisionar um app; essas são ações do sistema, e uma página web não deveria executá-las. Ele não valida assinaturas de código nem permissões de provisionamento contra a Apple, de modo que um .mobileprovision editado pode ser analisado perfeitamente e ainda assim ser rejeitado pelo sistema porque sua assinatura não bate mais — analisar não é confiar. E ele não executa nada do plist: uma tarefa do launchd que aponta para um script é dado até o launchd executá-la, e o workbench a trata como dado. Para o equivalente no Android — o manifesto dentro de um APK — use o Analisador de APK; para o primo do launchd no Linux, as units do systemd, use o Auditor de units do systemd.

Teste você mesmo: uma tarefa do launchd que você pode ler, converter e verificar

# A minimal launchd job, as XML — the form you can read and edit safely
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.example.backup</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/backup.sh</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>StartCalendarInterval</key>
    <dict>
        <key>Hour</key>
        <integer>3</integer>
        <key>Minute</key>
        <integer>30</integer>
    </dict>
</dict>
</plist>

# Convert between the two forms on a Mac — never edit the binary bytes:
$ plutil -convert xml1 job.plist     # binary -> readable XML
$ plutil -convert binary1 job.plist  # XML -> compact binary, for shipping
$ plutil -lint job.plist             # re-parse to verify it is still valid

Fontes

Perguntas frequentes

Abri um .plist num editor de texto e ele parece lixo — o arquivo está quebrado?

Quase certamente não: é um plist binário. Abra o arquivo e olhe os primeiros bytes — se eles dizem bplist00, o arquivo está na forma binária compacta da Apple, feita para máquinas, não para olhos. Converta-o primeiro para XML (plutil -convert xml1 num Mac, ou cole-o no Plist Workbench, que detecta a mágica e o converte por você) e você verá as mesmas chaves e valores em forma legível. Só se preocupe se o arquivo não começar nem por bplist00 nem por

Posso editar um .mobileprovision ou um .mobileconfig da mesma forma?

O formato é o mesmo — ambos são plists por baixo — mas as consequências diferem. Um .mobileconfig é um plist simples e é editado sem problemas. Um .mobileprovision é um plist envolvido numa assinatura CMS, de modo que mudar um valor dentro dele quebra a assinatura, e as ferramentas da Apple rejeitarão o perfil editado mesmo que ele continue sendo analisado. O workbench analisa e edita ambos, mas não valida assinaturas contra a Apple, então trate um .mobileprovision analisado como "legível", não como "ainda válido". Na dúvida, regenere o perfil no portal da Apple em vez de editá-lo.

Por que o launchd ignora minha tarefa, ou se recusa a carregá-la?

Verifique os suspeitos habituais nesta ordem. Primeiro, o Label está presente, é uma string e é único? Segundo, o ProgramArguments é um array de strings — uma única string ali é a falha mais comum. Terceiro, os campos de StartCalendarInterval estão dentro do intervalo — um Hour de 25 significa que a tarefa nunca executa. Quarto, rode plutil -lint no arquivo para detectar XML malformado, e verifique se o arquivo mora no diretório certo (~/Library/LaunchAgents para o seu usuário, /Library/LaunchDaemons para o sistema) com o dono certo. Se ainda assim não carregar, cole-o no Plist Workbench — suas verificações de launchd sinalizam cada um desses problemas com uma correção em linguagem simples.