class JobDump

This must be called after CollectJob and before other dumping calls. It

dumps the job archive header and the information CollectJob found. This

alone results in a valid "stub" job archive that gives some summary data

about the job but doesn't include any process or child dumps. On success,

its result's size_t value() is the total size written so far, which by

itself is already a valid archive file image for the "stub" job archive.

This writes out the header at the beginning of an archive file.

This begins a new file of the archive by streaming out its archive member

file header, which has a small fixed size. The format requires that this

come after everything DumpHeaders writes. The size of the member file

must already be known, though its contents can be streamed out piecemeal

after this. After the headers written by DumpHeaders, a job archive

consists of any number of member files. Each is either an ELF `ET_CORE`

file representing a process in this job; or another whole job archive

representing a child job. The name of each file chosen by the dump-writer

need not be meaningful and is truncated to a short limit (16). Each file

is understood based on its own format and contents, though names friendly

to human readers of `ar tv` output are recommended.

A single Collector cannot be used for a different job later. It can be

clear()'d to reset all state other than the job handle.

Collect privileged system-wide information from the kernel. This is

always optional, but it must always be called before CollectJob, if it's

called at all. The kernel information is included in the total size

returned by CollectJob. Note this only works if the zxdump::TaskHolder

from which the zxdump::Job being dumped was loaded has had the root

resource inserted (either the real live object or from a dump).

Collect system-wide information. This is always optional, but it must

always be called first, before CollectJob, if called at all. The system

information is included in the total size returned by CollectJob.

Add dump remarks. This can be called any number of times, but must be

called before CollectJob if it's called at all.

Collect information about the job itself. The result contains the size of

the job archive to dump just that information. Note that this collection

is completely asynchronous with respect to the job and any process within

it. The dump will be conducted on the basis of this data, but even as new

processes or child jobs come and go, they will not be collected. (There

is no analog to zx::ProcessDump

<

...>::SuspendAndCollectThreads for jobs.)

Return the size that DumpMemberHeader will always consume.

This can be used either before or after using DumpHeaders or other calls.

This acquires job handles for all the child jobs CollectJob found; if

CollectJob wasn't called, then this does the necessary portion of its

work. (If DumpHeaders is called after CollectChildren but before

CollectJob, then the job archive will not include all the normal job

information, but only the job information that lists the child KOIDs.)

Any job KOIDs that cannot be found are simply ignored as races with old

jobs being cleaned up.

The caller can then create a JobDump object for each job and stream it out

after calling DumpMemberHeader.

This can be used either before or after using DumpHeaders or other calls.

This acquires process handles for all the direct-child processes

CollectJob found; if CollectJob wasn't called, then this does the

necessary portion of its work. (If DumpHeaders is called after

CollectProcesses but before CollectJob, then the job archive will not

include all the normal job information, but only the job information that

lists the process KOIDs.) Any process KOIDs that cannot be found are

simply ignored as races with old processes dying.

The caller can then create a ProcessDump object for each process and

stream it out after calling DumpMemberHeader.