Platforms
Platforms
rqm reads requirement files, the configuration and test reports from a project tree it does not control. This page says what rqm guarantees about those reads on each platform, and what it does not.
What is guaranteed
Every file below the project root is opened without following links, and what was opened is checked before it is read. A path that goes through a symbolic link, a junction or another reparse point is refused with E-PATH-SYMLINK and exit code 2. A path that is not a regular file is refused with E-PATH-NOT-FILE. A pipe, a device or a directory therefore cannot hang or confuse a run.
A hard link inside the root is accepted: it is an ordinary file with two names.
The guarantee covers the components below the project root. The root itself, and the directories above it, may be reached through links. When RQM_CONFIG is set, the root is the directory of that file, and the file itself must not be a link.
Every file is read once into a buffer. The hash and the parse are made from that same buffer, so a hash never belongs to a different version of the file than the one that was parsed. rqm keeps no cache between runs: it hashes the content, never a modification time.
Configured paths are checked as text before anything is opened, on every platform, so that a project reads the same way everywhere. A path with an empty, . or .. component, a backslash, a colon or another character that Windows forbids, a trailing dot or space, or a reserved device name such as NUL or COM1 is refused with E-PATH-INVALID.
Files are written atomically: to a temporary file in the same directory, flushed, then renamed over the target. A reader sees the old file or the new file, never half of one. A crash may leave a temporary file behind. Discovery ignores those, and the next write removes its own leftovers.
Per platform
Linux
The root is a directory descriptor. Each component is opened relative to the one before it with O_NOFOLLOW, the last one without blocking, and the opened descriptor is checked to be a regular file. A link swapped in at any depth, at any time, is refused and never followed.
macOS
The same walk as on Linux, with the same system calls. Writes flush with F_FULLFSYNC, because a plain fsync on macOS does not reach the disk.
Windows
The root is opened once and its final path is read. A file is opened below that path without following a link in the last component. Then the opened handle is checked: it is not a reparse point, it is a file on a disk, and its final path equals the root’s final path followed by the spelled components, compared without regard to case. That last check refuses 8.3 short names, trailing-dot spellings and alternate data streams, which the operating system would otherwise resolve to the same file.
Creating files on Windows (rqm init, rqm create, run records and logs) uses only the standard library: a file that must not exist is written to a temporary name and hard linked to its final name, which fails if the name is taken. This code is shared with the other platforms and tested there, but its tests on Windows itself have not been run yet. Unlike the read path, it checks the directories and then creates the file: there is no check of the opened handle, so a link put in place between the two steps by a process that can write inside the project is followed. It also needs a file system with hard links (NTFS or ReFS, not FAT or exFAT); on one without, creating a file fails with an error that names the path.
Creating symbolic links on Windows needs privilege or developer mode. Junctions need neither. The tests that need a link skip, and print why, when they cannot create one.
Child processes
Suites run as child processes, and what rqm does to start them and to end them differs by platform. docs/RUNNING.md has the details. In short: on Unix a suite runs in a process group of its own and is ended with SIGTERM, then SIGKILL after 5 seconds. On Windows a suite is started suspended, put into a Job Object with kill-on-close and no breakaway, then resumed, and the job is terminated at once on a timeout. The Windows code is the only unsafe code besides the file layer, and it is limited to one module with a fixed number of blocks.
What is not guaranteed
The race is narrowed, not eliminated. On Linux and macOS the walk leaves no window between checking a component and using it. On Windows the check runs on the handle after the open, so a component swapped between the open and the final-path query could slip through for that moment. In both cases a process that can write inside the project tree while rqm runs can change what rqm reads, and rqm does not claim to defend against a hostile writer. It guarantees that a stray link or special file in a checked-out repository is not followed.
Case-insensitive and Unicode-normalizing file systems may treat two spellings as one file. Discovery lists names as they are on disk, and rqm does not fold them.