SCRYDOSBox-XReferenceMachinelogAlso in MAME
log
Read the newest log lines that match a pattern: the program's, the emulator's, both, or the DOS calls the program made.
log(pattern, channel, limit=40, labels=false, since_mark=0)
Try it
logfile, after a ball was served and lost.What did the game log about serves, hits and lost balls?
log(pattern="SERVE|HIT|LOST", channel="guest"){
"summary": "log guest /SERVE|HIT|LOST/: 6 of 6 lines",
"lines": [
"Bochs port E9h: HIT 0 7",
"Bochs port E9h: HIT 5 6",
"Bochs port E9h: HIT 5 0",
"Bochs port E9h: SERVE",
"Bochs port E9h: HIT 5 9",
"Bochs port E9h: LOST"
]
}Six lines of the game's own log match, oldest first. Each opens with Bochs port E9h:, the emulator's mark on a line the program wrote to port 0xE9.
The whole reply
{
"summary": "log guest /SERVE|HIT|LOST/: 6 of 6 lines",
"status": "ok",
"pattern": "SERVE|HIT|LOST",
"channel": "guest",
"lines_total": 6,
"truncated": false,
"lines": ["Bochs port E9h: HIT 0 7", "Bochs port E9h: HIT 5 6", "Bochs port E9h: HIT 5 0", "Bochs port E9h: SERVE", "Bochs port E9h: HIT 5 9", "Bochs port E9h: LOST"]
}Arguments
- pattern string, required
- A regular expression each line is searched for. It is never empty:
.matches every line. - channel one of
"guest","emulator","all","dos", required - Which log to read.
guestis the program's port 0xE9 lines,emulatorDOSBox-X's own,allboth with each line tagged,dosthe program's INT 21h calls. - limit integer (>= 1, <= 400), default
40 - How many of the newest matching lines to return: 1 to 400. Left out, 40.
- labels boolean, default
false trueaddslabels: the lines returned, counted by their first word. Left out, no count.- since_mark integer (>= 0), default
0 - A byte position in the log: only lines written after it are read. Left out or 0, the whole log is read.
What comes back
- lines
- The newest
limitmatching lines, oldest first. Not ondos. - lines_total
- How many lines matched in all, not how many came back.
- truncated
truewhen more matched than came back.- labels
- With
labels=true, the returned lines counted by their first word: a quick view of who is writing. - calls
- On
dos, the matching calls in place oflines, each with the registers DOS took, the ones it handed back and its result. - calls_dropped
- On
dos, how many of the oldest calls the server no longer holds.
All 8 reply fields
calls(array)calls_dropped(integer)channel(string)labels(object)lines(array)lines_total(integer)pattern(string)truncated(boolean)
What it refuses
- An empty pattern, or one that is not a regular expression (
bad_argument). - A
limitoutside 1 to 400 (bad_argument). - A session started without
logfile, a log not written yet, orgueston a log with no line from the program (no_channel). doson a session not started withdos_calls(no_channel).doswithlabelsorsince_mark: the calls are not lines of the log file (bad_argument).channelprocess: the emulator's own output is not a log;close(detail=true)returns its last lines (bad_argument).- A
since_markpast the end of the log (bad_argument).
Why it works this way
guest, emulator and all are three views of one file, so one since_mark position serves all three. all is the file in order, each line tagged [guest] or [emulator] .
dos is another record: every INT 21h call the program made, with its result, on a session started with dos_calls. There pattern is matched against each call's line and lines_total counts calls.
An empty lines is an answer: nothing matched. A log with no line from the program at all is refused, so that silence is never read as no match. While the program runs a line it has only now written may not be in the file yet, and note says so.
More on why
- On
dos, each call is two rows of the debugger'sDOSTRACE, one as DOS takes it and one as DOS hands it back, paired by number. - On
dos, each call ofcallsholdsinandout, the registers DOS took and handed back;out.cfis the carry flag. erroris the code and its name, for the calls that report failure by the carry: AH 38h and up. An older call answers in AL and gets none.returnedisfalsefor a call DOS has not handed back yet, as at a stop inside it.switched: truemarks a call that never returned to its caller, as an EXEC or an exit: the registers are then another program's, so no result is claimed.- The emulator's own
int21andfileiolines, switched on in the conf's[log]section, are written before DOS runs the call, so they never carry its result. time_sandreturned_sare seconds of emulated time since power-on, the clockrun_forreports.
Related tools
The contract your client receives
The session's log, one `channel` (`guest`, `emulator`, `all`, `dos`) filtered by the
Python regex `pattern`; `limit` keeps the newest matches; `labels=True` adds `labels`, the
matching lines counted by first word.
`since_mark` (a byte position, from a `mark`) reads only what follows. Needs a session with
`logfile`. `dos`, the guest's INT 21h calls and no other interrupt, instead needs a session
started with `dos_calls`, matches `pattern` against each call's `line` (`#20 08BC:0139 psp
0x08BC 0x3D open MISSING.TXT -> error 2 file not found`), counts calls where the others count
lines (the matches among the calls the server holds), and takes no `since_mark` or `labels`;
past those, `calls_dropped` says how many of the oldest went. Works on a running guest.
Reply: `channel`, `lines` (not on `dos`), `lines_total`, `truncated`, `labels`, `pattern`,
`note`; on the DOS channel `calls` instead of `lines` (each `n`, `time_s`, `cpu_mode`,
`caller`, `psp`, `function`, `name`, `file`, `in`, `out`, `error`, `returned`, `returned_s`,
`switched`, `line`), and `calls_dropped` (on `dos`, past the calls held). INVALID with `code`:
no `logfile`, no log yet, no guest instrumentation, `limit` out of range, an empty or bad
pattern, an unknown channel (`process` is refused by name), a `since_mark` naming no
position. To wait for a line use `log_wait`.
Reference: REFERENCE.md, The log.