SCRYMAMEReferenceMachinelogAlso in DOSBox-X

MAMEMachine

log

Read the newest log lines that match a pattern: from MAME's own log, from the process's output, or from both.

log(pattern, channel, limit=40, labels=false, since_mark=0)

Try it

On Gridlee, a free ROM from mamedev.org, after one coin has been dropped.
Ask

What has MAME logged about the coin counter?

Call
log(pattern="coin counter", channel="emulator")
Reply 2 of 7 fields
{
  "summary": "log emulator /coin counter/: 3 of 3 lines",
  "lines": ["[:] coin counter off", "[:] coin counter on", "[:] coin counter off"]
}

Three lines of MAME's own log match, oldest first: the driver reports the coin counter off, then on for the coin, then off again.

The whole reply
JSON
{
  "summary": "log emulator /coin counter/: 3 of 3 lines",
  "status": "ok",
  "pattern": "coin counter",
  "channel": "emulator",
  "lines_total": 3,
  "truncated": false,
  "lines": ["[:] coin counter off", "[:] coin counter on", "[:] coin counter off"]
}

Arguments

pattern string, required
A regular expression each line is searched for. It is never empty: . matches every line.
channel one of "emulator", "process", "all", required
Which log to read. emulator is MAME's error.log, process its stdout and stderr, all both with each line tagged [emulator] or [process] .
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
true adds labels: 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 limit matching lines, oldest first.
lines_total
How many lines matched in all, not how many came back.
truncated
true when more matched than came back.
counts
On all, how many lines matched in each of the two logs.
labels
With labels=true, the returned lines counted by their first word: a quick view of who is writing.
All 7 reply fields
  • channel (string)
  • counts (object)
  • labels (object)
  • lines (array)
  • lines_total (integer)
  • pattern (string)
  • truncated (boolean)

What it refuses

Why it works this way

A driver can fill the log fast, so the pattern and the limit are how a line is found. Pass a pattern that narrows: . is the last resort, and labels shows at a glance who is writing.

emulator is what MAME's core and the drivers write with logerror. process is where MAME's own error messages, its -verbose output and a driver's counters go.

since_mark takes the mark that a state load, or the log part of a stop's reply, gives for that log. It is a position in one file, so all, which reads two, takes none.

The contract your client receives
Text
The newest lines of one `channel` of what MAME writes matching the regex `pattern` (`.` for
all; never empty). Works while running.

`channel`: `emulator`, `process` or `all` (lines tagged `[emulator] `, `[process] `);
`guest` is refused. `labels=True` adds `labels`, lines counted by first word.
`since_mark` reads only what follows that log byte position.

Reply: `pattern`, `channel`, `lines` (the newest `limit`, 1..400, oldest first),
`lines_total`, `truncated`, `counts` (on channel `all`), `labels`. A bad `limit`, regex or
`since_mark` is refused.

Reference: REFERENCE.md, The log.
Tools