SCRYDOSBox-XReferenceSessioncloseAlso in MAME
close
End the session and the emulator with it, and learn how it ended.
close(detail=false)
Try it
We are done: close the emulator and tell me how it ended.
close(){
"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
{
"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 truereturns 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
truewhen a session was ended;falsewhen there was none to close.- ended_by
- How it ended:
quit,killed,diedornone. - exit_code
- The emulator's exit code. It is
available: falsewith awhywhen no session was running or the killed process could not be collected. - pid
- The process this call ended, or
available: falsewith awhywhen no session was running. - guest_files
- Each file
startnamed inguest_files, with thestatethatguest_filereports for it. - draft
- The names of what the session saved and
promotehas 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, becausestartturns its quit warning off. -
killed: a conf that turns the warning back on, or a program that ignored the request.exit_codeis 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
QUITon Windows, which has no signal to ask with; the kill is SIGKILL, or a terminate on Windows. -
A
notesays the emulator's output was not read to its end, so the last lines may be short.
Related tools
The contract your client receives
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`.