os.md

Operating system

Reference index · Official Lua 5.2 OS library · C Lua 5.2.4 source · Implementation

Install with state.OpenOperatingSystemLibrary(). Time, environment, process exit, and filesystem operations are routed through LuaPlatform providers where indicated. Default providers use .NET APIs; Unity/custom providers can behave differently.

API / official reference	Inputs and result	Lua-CSharp implementation notes and differences
os.clock()	Returns elapsed CPU time in seconds.	Host-dependent: calls ILuaOsEnvironment.GetTotalProcessorTime. The default reads the current .NET process's total processor time, including host work outside Lua.
os.date([format [, time]])	Formats a timestamp, or returns date fields for *t; a leading ! selects UTC. Defaults to current time and %c. Explicit timestamps are truncated toward zero to whole Unix seconds, as in C Lua 5.2.	Uses managed date/time formatting and the configured TimeProvider.LocalTimeZone rather than C strftime/process timezone state. Names and composite formats use the C-locale conventions below.
os.difftime(t2 [, t1])	Returns the difference in whole Unix seconds. Both timestamps truncate toward zero before subtraction; omitted/nil t1 defaults to zero, as in C Lua 5.2.4's implementation.	Converts to managed 64-bit seconds and subtracts as doubles, without integer subtraction overflow. C time_t ranges vary by build; unlike the Windows C runtime, managed arithmetic supports negative timestamps. The official manual lists both arguments, but the C implementation also accepts the zero default.
os.execute([command])	Officially runs a shell command or queries shell availability.	Unsupported operation: no command/nil returns false; supplying a command raises a not-supported error. The library has no shell-execution implementation.
os.exit([code [, close]])	Requests termination with a numeric code or boolean success/failure code. Numeric strings are coerced and fractions truncated toward zero to a managed 32-bit code.	Host-dependent: default SystemOsEnvironment calls Environment.Exit; Unity uses its application exit provider. Limitation: close is ignored, so the Lua state is not explicitly disposed before exiting.
os.getenv(name)	Returns an environment value or nil.	Host-dependent: default provider reads process environment variables; custom/Unity providers may expose a managed dictionary instead. Names/results are converted between byte strings and .NET text when needed.
os.remove(filename)	Removes a file or, on POSIX hosts, an empty directory. Returns true on success or nil, message, code for handled I/O/permission failures.	The default provider uses .NET filesystem operations and never removes directories recursively. Windows rejects directory removal, matching its C runtime. Handled errors use .NET HResult codes.
os.rename(oldname, newname)	Moves/renames a file or directory; reports success or handled failure.	Host-dependent: default provider uses File.Move/File.Replace and Directory.Move. Directory replacement restrictions follow .NET/host filesystem behavior rather than C rename; .NET Standard 2.1 uses File.Replace for an existing file destination.
os.setlocale([locale [, category]])	Queries the fixed locale with omitted/nil input, or accepts C; both return C. Validates all, collate, ctype, monetary, numeric, and time categories; the default is all.	Limitation: other locale strings return nil; no C or .NET locale is changed. Date formatting stays invariant; string casing/classification follows the string library's rules.
os.time([table])	Without a table, returns current Unix seconds. With a table, reads local date fields through __index, accepts numeric strings, truncates fractions toward zero, and normalizes calendar overflow such as day 0 or month 13. Invalid/missing optional hour/minute/second fields default to 12/0/0; invalid/missing required year/month/day fields raise an error. The input table remains unchanged, as in C Lua 5.2.4.	Current time and the local timezone come from TimeProvider, consistently with os.date. Conversion returns nil for dates outside managed date/time ranges or timestamp -1, Lua 5.2's failure sentinel. __index callbacks cannot Lua-yield through this library boundary, but C# callbacks can await. See below for remaining timezone differences.
os.tmpname()	Returns a temporary pathname.	Host-dependent: default Path.GetTempFileName creates an empty file while choosing the name. The caller owns cleanup; unlike io.tmpfile, this API does not attach delete-on-close behavior. The name uses the state's string representation.

Date conversion details

The date formatter implements a managed mapping of POSIX strftime conversions. It uses fixed C-locale forms rather than the host C locale. The following conversions are recognized:

%a %A %b %B %c %C %d %D %e %F %g %G %h %H %I %j %m %M %n %p %r %R %S %t %T %u %U %V %w %W %x %X %y %Y %z %Z %%

Formatting rules and remaining differences:

• %U and %W count weeks starting on Sunday and Monday respectively, with days before the first such day in week 00. %V, %g, and %G use the ISO week number and week-based year. These POSIX conversions are available here even when a non-POSIX C Lua build rejects them.
• %z emits a signed offset as HHMM, without a colon. %Z emits UTC for UTC and the configured timezone's .NET standard/daylight name otherwise; these names can differ from C runtime abbreviations. Both omitted and explicit timestamps use the same timezone rules.
• Month/day names are invariant English. %c uses ddd MMM dd HH:mm:ss yyyy with a space-padded day, %x uses MM/dd/yy, %X uses HH:mm:ss, and %r uses hh:mm:ss AM/PM. These follow POSIX C-locale forms; a particular C runtime's locale-dependent composites can differ. Changing os.setlocale has no effect.
• Valid POSIX %E/%O modifiers use the same C-locale conversions as their unmodified forms: %E accepts cCxXyY, and %O accepts deHImMSuUVwWy. Unknown conversions and invalid/incomplete modifier pairs raise an error.

Timestamp conversion is bounded by .NET date/time ranges. For byte-string states, format literals remain byte-string units and managed timezone names are encoded as text. Use the official link for the complete Lua/C contract and this list for the implemented behavior.

Date-table normalization uses the first day of the normalized year/month, then adds the day and time offsets. Both that anchor and the resulting date must fit .NET's years 1–9999. C mktime ranges and integer field widths depend on the platform; managed conversion does not emulate every C runtime's limits.

During a repeated local hour, a truthy isdst selects the daylight-saving occurrence and false selects standard time. Nil/omitted isdst uses .NET's standard-time default for ambiguous dates. This preserves os.time(os.date('*t', timestamp)) across the repeated hour, including negative daylight-saving adjustments. Remaining limitation: for an unambiguous date, isdst does not force a seasonal correction as C mktime can; the timezone's applicable offset is used.