# System, Time and Random

## System.args

```signature
System.args() -> List[String]
```

Gives the words after the file name: `agentica tool.agc a b` gives `["a", "b"]`.

```agentica
def main() -> Void
  args = System.args()
  puts("#{args.size} arguments")
end
```

```output
0 arguments
```

## System.exit

```signature
System.exit(code: Int) -> Void
```

Ends the program at once, with an exit code.

```agentica
def main() -> Void
  puts("before")
  System.exit(3)
  puts("never printed")
end
```

```output
before
```

## System.env

```signature
System.env(name: String) -> Result[String]
```

Reads an environment variable of the program. With `--deny-env` (or `--sandbox`) it returns an error that begins with `denied: --deny-env`. There is no call that lists all variables.

- A variable that is not set is an error. A variable set to the empty string is `ok("")`.
- A name that is empty, or has `=` or a NUL in it, is an error.
- A value that is not valid UTF-8 is not an error. Each byte that is not part of a valid UTF-8 sequence becomes U+FFFD.
- The home directory is `System.env("HOME")`.

```agentica
def main() -> Void
  editor = System.env("AGENTICA_EXAMPLE_NOT_SET").unwrap_or("vi")
  puts(editor)
  puts(System.env("A=B").ok?)
end
```

```output
vi
false
```

The VM hides the variables it keeps for itself:

- `AGENTICA_CHANNEL`, and `UV_USE_IO_URING` when the VM set it. A program started with `Process.spawn` does not get them either.
- `AGENTICA_VM_METRICS` and `AGENTICA_VM_METRICS_FILE` are reserved for the VM metrics. A program started with `Process.spawn` does not get them, but `System.env` still shows them to your program.

## System.os

```signature
System.os() -> String
```

The operating system of the running program. It needs no flag.

- `"linux"`, `"macos"` or `"windows"`.
- On any other system, the lowercase name that `uname` gives.
- `"unknown"` when the system cannot say, or when the name is not printable ASCII.

```agentica
def main() -> Void
  puts(System.os().length > 0)
end
```

```output
true
```

## System.pid

```signature
System.pid() -> Int
```

The process id of the running program. It needs no flag. Pass it to `--driver-pid` when you start a VM. That VM then checks that its parent is this program.

```agentica
def main() -> Void
  puts(System.pid() > 0)
end
```

```output
true
```

## System.subscribe

```signature
System.subscribe(signals: List[System.Signal]) -> Result[Channel[System.Signal]]
```

Receives the listed operating system signals as values on a new channel, instead of letting them stop the program. `System.Signal` is an enum: `Term`, `Int` (Ctrl-C), `Hup`, `Usr1`, `Usr2`, `Quit` and `Kill`; the first five can be subscribed to. A program that must clean up on Ctrl-C or on a container stop receives the first value, cleans up, and exits with `128 + System.signal_number(signal)`, the code a shell expects.

- The channel holds one pending value per signal: a value is queued only when that signal has none waiting, so a burst of one signal gives one value and the signal never waits for the program. The channel does not count how many times a signal came.
- Each subscription gets every signal it lists, so two tasks that subscribe to `Term` both get it. A signal listed twice counts once.
- The calling task owns the channel, like a handle. When that task ends, in any way, or the channel is closed, the subscription ends: the values still queued can be received, then `recv` returns `channel: closed`. When the last subscription to a signal ends, that signal stops the program again.
- A signal that comes before the subscription stops the program, as it does without one. While a subscription is open the run waits for its signals, so a program whose tasks all wait for one does not end.
- `send` on the channel, or on its address, returns `error("signal: channel is read only")` with kind `argument`.
- `Quit` or `Kill` in the list stops the run with `RUNTIME-INVALID-SIGNAL`. `Quit` (`Ctrl-\`) is the force stop: it stops the child programs, writes the files and exits with 131, also in a program that subscribed to `Term` and `Int`, unless the program started with `Quit` ignored (a job that a shell runs in the background). `Kill` cannot be caught.
- An empty list returns `error("signal: no signals")` with kind `argument`. A signal that the program started with ignored (`nohup`; `Int` and `Quit` for a job that a shell runs in the background) stays ignored and the other listed signals are subscribed; when every listed signal was ignored, the call returns `error("signal: ignored when the program started")` with kind `system.signal`. On Windows every call returns `error("signal: not supported on this system")` with kind `system.signal`, and Ctrl-C and Ctrl-Break stop the program.
- It needs no flag, also under `--sandbox`: it only changes what the program does with its own signals.
- `SIGPIPE`, `SIGCHLD` and the signals of the VM's garbage collector have no `System.Signal` value, so a program cannot take them. A program started with `Process.spawn` starts with the default action for every signal.

```agentica
def main() -> Void
  signals = System.subscribe([System.Signal.Term]).unwrap!
  case signals.recv(100)
    ok(signal) -> System.exit(128 + System.signal_number(signal))
    error(e) -> puts(e.message)
  end
end
```

```output
channel: timed out
```

## System.signal_number

```signature
System.signal_number(signal: System.Signal) -> Int
```

The number of the signal: `Term` is 15, `Int` 2, `Hup` 1, `Quit` 3 and `Kill` 9. `Usr1` and `Usr2` are 10 and 12 on Linux and Windows, 30 and 31 on macOS. A process that a signal ended has the exit code `128 +` that number.

```agentica
def main() -> Void
  puts(System.signal_number(System.Signal.Term))
end
```

```output
15
```

## System.signal

```signature
System.signal(pid: Int, signal: System.Signal, comm: String) -> Result[Void]
```

Sends a signal to a process that is not your program's child, such as a program that a child started. `comm` is the process's name as Linux keeps it in `/proc/<pid>/comm`: the file name of the program, cut to 15 bytes (`Runner.Listener`). The signal goes only to the process that has that pid and that name when the call runs: the VM holds the process with a pidfd while it compares the name, and signals through it, so a process that took a reused pid is never reached. For your program's own children use `Process.signal`.

- A pid of 0 or less, or your program's own, returns `error("signal: pid must be above 0 and not the program's own")`, and an empty `comm` or one over 15 bytes returns `error("signal: comm must be 1 to 15 bytes without NUL")`, both with kind `argument`.
- Another name returns `error("signal: the process has another name")` with kind `system.signal`, and the process gets nothing. A process that has ended, or one of another user, returns an error that starts with `signal: cannot signal the process`, with kind `process.failed` and the system's error number as its code.
- `--deny-run` turns it off: it returns `error("denied: --deny-run turns off signalling processes")`.
- It needs Linux 5.3 or later. On an older kernel, under a seccomp filter that refuses pidfds, and on macOS and Windows it returns `error("signal: pidfd is unavailable")` with kind `system.signal`.

```agentica
def main() -> Void
  pid = System.args()[0].to_i!
  case System.signal(pid, System.Signal.Term, "Runner.Listener")
    ok(_) -> puts("sent")
    error(e) -> puts(e.message)
  end
end
```

## Std.source

```signature
Std.source(path: String) -> Result[String]
```

The text of a `std/` source that the `agentica` binary carries, by its exact path in `stdlib/`: `"queue.agc"`, `"bdd/gherkin.agc"`, `"prelude/list.agc"`; `"internal/compiler/..."` is the private core of the front end that `std/analysis` uses. Any other path is an error, `"std/queue.agc"` and `"queue"` included. It needs no flag and reads only data of the binary, so tasks may call it at the same time. A doc or lint tool can read the std sources of the binary that runs it this way.

```agentica
def main() -> Void
  text = Std.source("queue.agc").unwrap_or("")
  puts(text.start_with?("## "))
  puts(Std.source("nope.agc").ok?)
end
```

```output
true
false
```

## FrontEnd

`FrontEnd.hand_off(program, options, arguments)`, `FrontEnd.std_source(path)` and `FrontEnd.stdin_bytes()` belong to the front end of the `agentica` binary. That binary compiles a program and hands it to the VM: `hand_off` takes the compiled program (a `Bytes`) and runs it in a new runtime with the given VM options and arguments, `std_source` reads an embedded `std/` source by its path in `stdlib/`, and `stdin_bytes` reads standard input to its end as a `Result[Bytes]` (an error over 16 MiB or when the read fails; a later call reads on from there). They are not for your programs: a program that calls them, and any front end run by `agentica run`, stops with `RUNTIME-FRONT-END-ONLY`. They need no flag.

## Time.now_ms

```signature
Time.now_ms() -> Int
```

Wall-clock time in milliseconds since 1970. It can jump when the system clock changes. `&Time.now_ms` is the clock as a value (`Fn[Int]`), to pass to code that a test gives a fixed clock.

```agentica
def main() -> Void
  puts(Time.now_ms() > 1700000000000)
end
```

```output
true
```

## Time.monotonic_ms

```signature
Time.monotonic_ms() -> Int
```

Milliseconds from an unknown start. The value never goes back. Use it to measure how long something takes. On a Linux host where reading the exact clock is a system call (such as an HPET clock source) it comes from the kernel's coarse clock, which is cheap to read and lags the exact time by up to about two kernel ticks (at most about 20 ms), but it is never behind an earlier `Time.monotonic_ns` or a `Task.sleep` that ended: after `Task.sleep(ms)` it has gone on by at least `ms`. Use `Time.monotonic_ns` for spans of a few milliseconds.

```agentica
def main() -> Void
  start = Time.monotonic_ms()
  Task.sleep(5)
  elapsed = Time.monotonic_ms() - start
  puts(elapsed >= 5)
end
```

```output
true
```

## Time.monotonic_ns

```signature
Time.monotonic_ns() -> Int
```

Nanoseconds from the same clock and the same unknown start as `Time.monotonic_ms`. They never go back. Use it for work too short for milliseconds. An `Int` holds about 292 years of nanoseconds, so the value does not overflow in practice.

```agentica
def main() -> Void
  start = Time.monotonic_ns()
  Task.sleep(5)
  elapsed = Time.monotonic_ns() - start
  puts(elapsed >= 4000000)
end
```

```output
true
```

## Random.int

```signature
Random.int(min: Int, max: Int) -> Int
```

A random `Int` from `min` to `max`, uniform. Both are included. `min > max` stops the program with `RUNTIME-INVALID-RANGE`.

```agentica
def main() -> Void
  roll = Random.int(1, 6)
  puts(roll >= 1 and roll <= 6)
end
```

```output
true
```

## Random.float

```signature
Random.float() -> Float
```

A random `Float` from `0.0` up to, but not including, `1.0`.

```agentica
def main() -> Void
  x = Random.float()
  puts(x >= 0.0 and x < 1.0)
end
```

```output
true
```

## Random.seed

```signature
Random.seed() -> Int
```

The seed of the run, from `0` to `2147483647`: the `N` of `--seed N`, or the one drawn from the operating system when there is no `--seed`. Every task gives the same number. Print it when something fails, then run again with `--seed` and that number to get the same random numbers.

```agentica
def main() -> Void
  seed = Random.seed
  puts(seed >= 0 and seed <= 2147483647)
end
```

```output
true
```

Each run gives other numbers. Run with `agentica --seed 42 file.agc` to get the same numbers every time (`N` is `0 .. 2147483647`, otherwise the exit status is 2). Without `--seed`, the generator is seeded from the operating system.

- Each task has its own generator. It is split from its parent when the task is spawned, so each task repeats its own numbers: the main task starts from the seed, and each spawn takes one draw from its parent. Timers, I/O and more than one scheduler can still change how tasks interleave, so a run of several tasks as a whole is not repeatable.
- Do not use `Random` for secrets: it is seeded, and `--seed` repeats it. Use [OpenSSL.Random](https://www.agentica-lang.com/agentica/library/text-and-data/crypto/index.md#random) for keys, tokens and IDs.
