SCRYDOSBox-XReferenceSessioncloseAlso in MAME

DOSBox-XSession

close

End the session and the emulator with it, and learn how it ended.

close(detail=false)

Try it

On Bricks, at the end of the example session's session.
Ask

We are done: close the emulator and tell me how it ended.

Call
close()
Reply 6 of 16 fields
{
  "summary": "close: quit, exit code 0",
  "status": "ok",
  "closed": true,
  "ended_by": "quit",
  "exit_code": 0,
  "omitted": ["stdout_tail", "errorlog_tail"]
}

DOSBox-X quit when asked, with exit code 0. omitted names the last lines it printed, which a clean quit leaves out.

The whole reply
JSON
{
  "summary": "close: quit, exit code 0",
  "status": "ok",
  "closed": true,
  "pid": "<volatile>",
  "conf": "./demos/bricks/bricks.conf",
  "conf_digest": "af0834584e2dad05",
  "watched": true,
  "bound_s": 900,
  "elapsed_s": "<volatile>",
  "captures": "off",
  "state_dir": "./tmp/demos/tour/files/states",
  "ended_by": "quit",
  "exit_code": 0,
  "omitted": ["stdout_tail", "errorlog_tail"],
  "how": "close(detail=True) keeps the emulator's last words on a clean quit too; once a close has answered its output is gone (the logfile stays at its path)",
  "draft": "<volatile>"
}

Arguments

detail boolean, default false
true returns the last lines the emulator printed (stdout_tail, errorlog_tail) after a clean quit too. Left out, they come only when the end was not clean.

What comes back

closed
true when a session was ended; false when there was none to close.
ended_by
How it ended: quit, killed, died or none.
exit_code
The emulator's exit code. It is available: false with a why when no session was running or the killed process could not be collected.
pid
The process this call ended, or available: false with a why when no session was running.
guest_files
Each file start named in guest_files, with the state that guest_file reports for it.
draft
The names of what the session saved and promote has not yet written into your repository's .scry/ folder.
All 18 reply fields
  • draft (array of string)
  • bound_s (number)
  • bundle (string)
  • captures (string)
  • closed (boolean)
  • conf (string)
  • conf_changed_on_disk (boolean or object)
  • image_changed_on_disk (boolean or object)
  • conf_digest (string)
  • elapsed_s (number)
  • ended_by (string)
  • errorlog_tail (string or object)
  • guest_files (array)
  • pid (integer or object)
  • state_dir (string)
  • stdout_tail (string)
  • output_bytes_dropped (integer)
  • watched (boolean)

Why it works this way

close ends the session now instead of leaving it to session_seconds. It asks DOSBox-X to quit and kills it only when the request is ignored; ended_by says which happened.

session describes the state after the close: alive, running and altered are false, as with no session.

The reply also says what the process was, in status's fields, read before the end. So pid is the process this call ended.

More on why
  • quit: DOSBox-X left when asked. A session started here does, with or without a program loaded, because start turns its quit warning off.

  • killed: a conf that turns the warning back on, or a program that ignored the request. exit_code is unavailable if the process is still not collected.

  • died: it had already exited.

  • none: there was no session.

  • The request is SIGTERM on macOS and the debugger's QUIT on Windows, which has no signal to ask with; the kill is SIGKILL, or a terminate on Windows.

  • A note says the emulator's output was not read to its end, so the last lines may be short.

The contract your client receives
Text
End the session deliberately rather than waiting for its bound.

Reply: `closed`, `ended_by` (`quit`, `killed`, `died`, `none`), `pid` and
`exit_code`, each an integer, or unavailable with its `why` when no session was running;
`stdout_tail` and `errorlog_tail` when the end was not a clean `quit`, or with `detail=True`;
`note` when the output was not read to its end. `guest_files`: each file `start` named, with
`guest_file`'s `state`. `session` is the block as it is after the close (`alive` and
`running` false), and `draft` names the candidates the session left waiting for `promote`.
Tools