std/os (original) (raw)

Source Edit

This module contains basic operating system facilities like retrieving environment variables, working with directories, running shell commands, etc.

Example:

import std/os let myFile = "/path/to/my/file.nim" assert splitPath(myFile) == (head: "/path/to/my", tail: "file.nim") when defined(posix): assert parentDir(myFile) == "/path/to/my" assert splitFile(myFile) == (dir: "/path/to/my", name: "file", ext: ".nim") assert myFile.changeFileExt("c") == "/path/to/my/file.c"

See also:

Imports

ospaths2, oscommon, osfiles, osdirs, ossymlinks, osappdirs, since, cmdline, strutils, pathnorm, syncio, assertions, widestrs, posix, times, oserrors, envvars, osseps

Consts

ExeExts = [""]

Platform specific file extension for executables. On Windows ["exe", "cmd", "bat"], on Posix [""].Source Edit

invalidFilenameChars = {'/', '\', ':', '*', '?', '"', '<', '>', '|', '^', '\x00'}

Characters that may produce invalid filenames across Linux, Windows and Mac. You can check if your filename contains any of these chars and strip them for safety. Mac bans ':', Linux bans '/', Windows bans all others.Source Edit

invalidFilenames = ["CON", "PRN", "AUX", "NUL", "COM0", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9", "LPT0", "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9"]

Filenames that may be invalid across Linux, Windows, Mac, etc. You can check if your filename match these and rename it for safety (Currently all invalid filenames are from Windows only).Source Edit

Procs

proc createHardlink(src, dest: string) {....raises: [OSError], tags: [], forbids: [].}

Create a hard link at dest which points to the item specified by src.

**Warning:**Some OS's restrict the creation of hard links to root users (administrators).

See also:

proc execShellCmd(command: string): int {....gcsafe, extern: "nos$1", tags: [ExecIOEffect], raises: [], forbids: [].}

Executes a shell command.

Command has the form 'program args' where args are the command line arguments given to program. The proc returns the error code of the shell when it has finished (zero if there is no error). The proc does not return until the process has finished.

To execute a program without having a shell involved, use osproc.execProcess proc.

Examples:

discard execShellCmd("ls -la")

Source Edit

proc exitStatusLikeShell(status: cint): cint {....raises: [], tags: [], forbids: [].}

Converts exit code from c_system into a shell exit code.Source Edit

proc expandFilename(filename: string): string {....gcsafe, extern: "nos$1", tags: [ReadDirEffect], raises: [OSError], forbids: [].}

Returns the full (absolute) path of an existing file filename.

Raises OSError in case of an error. Follows symlinks.

Source Edit

proc fileNewer(a, b: string): bool {....gcsafe, extern: "nos$1", raises: [OSError], tags: [], forbids: [].}

Returns true if the file a is newer than file b, i.e. if a's modification time is later than b's.

See also:

proc findExe(exe: string; followSymlinks: bool = true; extensions: openArray[string] = ExeExts): string {. ...tags: [ReadDirEffect, ReadEnvEffect, ReadIOEffect], raises: [OSError], forbids: [].}

Searches for exe in the current working directory and then in directories listed in the PATH environment variable.

Returns "" if the exe cannot be found. exe is added the ExeExts file extensions if it has none.

If the system supports symlinks it also resolves them until it meets the actual file. This behavior can be disabled if desired by setting followSymlinks = false.

Source Edit

proc getAppDir(): string {....gcsafe, extern: "nos$1", tags: [ReadIOEffect], raises: [], forbids: [].}

Returns the directory of the application's executable.

See also:

proc getAppFilename(): string {....gcsafe, extern: "nos$1", tags: [ReadIOEffect], raises: [], forbids: [].}

Returns the filename of the application's executable. This proc will resolve symlinks.

Returns empty string when name is unavailable

See also:

proc getCreationTime(file: string): times.Time {....gcsafe, extern: "nos$1", raises: [OSError], tags: [], forbids: [].}

Returns the file's creation time.

Note: Under POSIX OS's, the returned time may actually be the time at which the file's attribute's were last modified. See here for details.

See also:

proc getFileInfo(file: File): FileInfo {....raises: [IOError, OSError], tags: [], forbids: [].}

Retrieves file information for the file object.

See also:

proc getFileInfo(handle: FileHandle): FileInfo {....raises: [OSError], tags: [], forbids: [].}

Retrieves file information for the file object represented by the given handle.

If the information cannot be retrieved, such as when the file handle is invalid, OSError is raised.

See also:

proc getFileInfo(path: string; followSymlink = true): FileInfo {. ...raises: [OSError], tags: [], forbids: [].}

Retrieves file information for the file object pointed to by path.

Due to intrinsic differences between operating systems, the information contained by the returned FileInfo object will be slightly different across platforms, and in some cases, incomplete or inaccurate.

When followSymlink is true (default), symlinks are followed and the information retrieved is information related to the symlink's target. Otherwise, information on the symlink itself is retrieved (however, field isSpecial is still determined from the target on Unix).

If the information cannot be retrieved, such as when the path doesn't exist, or when permission restrictions prevent the program from retrieving file information, OSError is raised.

See also:

proc getLastAccessTime(file: string): times.Time {....gcsafe, extern: "nos$1", raises: [OSError], tags: [], forbids: [].}

Returns the file's last read or write access time.

See also:

proc getLastModificationTime(file: string): times.Time {....gcsafe, extern: "nos$1", raises: [OSError], tags: [], forbids: [].}

Returns the file's last modification time.

See also:

proc isAdmin(): bool {....raises: [], tags: [], forbids: [].}

Returns whether the caller's process is a member of the Administrators local group (on Windows) or a root (on POSIX), via geteuid() == 0.Source Edit

proc quoteShell(s: string): string {.noSideEffect, ...gcsafe, extern: "nosp$1", raises: [], tags: [], forbids: [].}

Quote s, so it can be safely passed to shell.

When on Windows, it calls quoteShellWindows proc. Otherwise, calls quoteShellPosix proc.

Source Edit

proc quoteShellCommand(args: openArray[string]): string {....raises: [], tags: [], forbids: [].}

Concatenates and quotes shell arguments args.

Example:

when defined(posix): assert quoteShellCommand(["aaa", "", "c d"]) == "aaa '' 'c d'" when defined(windows): assert quoteShellCommand(["aaa", "", "c d"]) == "aaa "" "c d""

Source Edit

proc quoteShellPosix(s: string): string {.noSideEffect, ...gcsafe, extern: "nosp$1", raises: [], tags: [], forbids: [].}

Quote s, so it can be safely passed to POSIX shell.Source Edit

proc quoteShellWindows(s: string): string {.noSideEffect, ...gcsafe, extern: "nosp$1", raises: [], tags: [], forbids: [].}

Quote s, so it can be safely passed to Windows API.

Based on Python's subprocess.list2cmdline. See this link for more details.

Source Edit

proc sameFileContent(path1, path2: string): bool {....gcsafe, extern: "nos$1", tags: [ReadIOEffect], raises: [IOError, OSError], forbids: [].}

Returns true if both pathname arguments refer to files with identical binary content.

See also:

proc setLastModificationTime(file: string; t: times.Time) {....raises: [OSError], tags: [], forbids: [].}

Sets the file's last modification time. OSError is raised in case of an error.Source Edit

proc sleep(milsecs: int) {....gcsafe, extern: "nos$1", tags: [TimeEffect], raises: [], forbids: [].}

Sleeps milsecs milliseconds. A negative milsecs causes sleep to return immediately.Source Edit

Exports

changeFileExt, /, splitFile, normalizeExe, normalizePath, cmpPaths, WriteDirEffect, ScriptExt, lastPathPart, isRelativeTo, absolutePath, isAbsolute, parentDir, unixToNativePath, /../, DirSep, normalizePathEnd, PathSep, normalizedPath, DynlibFormat, normalizePathEnd, addFileExt, joinPath, extractFilename, relativePath, FileSystemCaseSensitive, sameFile, ReadDirEffect, joinPath, CurDir, ExtSep, splitPath, tailDir, getCurrentDir, searchExtPos, parentDirs, AltSep, doslikeFileSystem, ExeExt, isRootDir, ParDir, tryRemoveFile, removeFile, copyFileToDir, moveFile, fileExists, FilePermission, getFilePermissions, CopyFlag, setFilePermissions, copyFileWithPermissions, copyFile, walkFiles, dirExists, existsOrCreateDir, walkDirRec, removeDir, walkDir, PathComponent, walkDirs, moveDir, createDir, copyDirWithPermissions, copyDir, walkPattern, setCurrentDir, symlinkExists, expandSymlink, createSymlink, getConfigDir, getCacheDir, getDataDir, getTempDir, getHomeDir, getCacheDir, parseCmdLine, paramCount, paramStr, commandLineParams, $, ==, newOSError, osErrorMsg, raiseOSError, osLastError, OSErrorCode, putEnv, envPairs, delEnv, getEnv, WriteEnvEffect, ReadEnvEffect, existsEnv, ExtSep, FileSystemCaseSensitive, DynlibFormat, DirSep, AltSep, PathSep, ScriptExt, doslikeFileSystem, ExeExt, CurDir, ParDir