std/private/osfiles

Source Edit

Imports

since, oserrors, oscommon, ospaths2, ossymlinks, winlean

Types

CopyFlag = enum
  cfSymlinkAsIs,            ## Copy symlinks as symlinks
  cfSymlinkFollow,          ## Copy the files symlinks point to
  cfSymlinkIgnore            ## Ignore symlinks

Copy options. Source Edit

FilePermission = enum
  fpUserExec,               ## execute access for the file owner
  fpUserWrite,              ## write access for the file owner
  fpUserRead,               ## read access for the file owner
  fpGroupExec,              ## execute access for the group
  fpGroupWrite,             ## write access for the group
  fpGroupRead,              ## read access for the group
  fpOthersExec,             ## execute access for others
  fpOthersWrite,            ## write access for others
  fpOthersRead               ## read access for others

File access permission, modelled after UNIX.

See also:

• getFilePermissions
• setFilePermissions
• os: FileInfo object

Source Edit

Procs

proc copyFile(source, dest: string; options = {cfSymlinkFollow}) {....gcsafe,
    extern: "nos$1", tags: [ReadDirEffect, ReadIOEffect, WriteIOEffect],
    raises: [OSError], forbids: [].}

Copies a file from source to dest, where dest.parentDir must exist.

On non-Windows OSes, options specify the way file is copied; by default, if source is a symlink, copies the file symlink points to. options is ignored on Windows: symlinks are skipped.

If this fails, OSError is raised.

On the Windows platform this proc will copy the source file's attributes into dest.

On other platforms you need to use getFilePermissions and setFilePermissions procs to copy them by hand (or use the convenience copyFileWithPermissions proc), otherwise dest will inherit the default permissions of a newly created file for the user.

If dest already exists, the file attributes will be preserved and the content overwritten.

On OSX, copyfile C api will be used (available since OSX 10.5) unless -d:nimLegacyCopyFile is used.

See also:

• CopyFlag enum
• osdirs: copyDir proc
• copyFileWithPermissions proc
• tryRemoveFile proc
• removeFile proc
• moveFile proc

Source Edit

proc copyFileToDir(source, dir: string; options = {cfSymlinkFollow}) {.
    ...raises: [ValueError, OSError],
    tags: [ReadDirEffect, ReadIOEffect, WriteIOEffect], forbids: [].}

Copies a file source into directory dir, which must exist.

On non-Windows OSes, options specify the way file is copied; by default, if source is a symlink, copies the file symlink points to. options is ignored on Windows: symlinks are skipped.

See also:

• CopyFlag enum
• copyFile proc

Source Edit

proc copyFileWithPermissions(source, dest: string;
                             ignorePermissionErrors = true;
                             options = {cfSymlinkFollow}) {....raises: [OSError],
    tags: [ReadDirEffect, ReadIOEffect, WriteIOEffect], forbids: [].}

Copies a file from source to dest preserving file permissions.

On non-Windows OSes, options specify the way file is copied; by default, if source is a symlink, copies the file symlink points to. options is ignored on Windows: symlinks are skipped.

This is a wrapper proc around copyFile, getFilePermissions and setFilePermissions procs on non-Windows platforms.

On Windows this proc is just a wrapper for copyFile proc since that proc already copies attributes.

On non-Windows systems permissions are copied after the file itself has been copied, which won't happen atomically and could lead to a race condition. If ignorePermissionErrors is true (default), errors while reading/setting file attributes will be ignored, otherwise will raise OSError.

See also:

• CopyFlag enum
• copyFile proc
• osdirs: copyDir proc
• tryRemoveFile proc
• removeFile proc
• moveFile proc
• osdirs: copyDirWithPermissions proc

Source Edit

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

Retrieves file permissions for filename.

OSError is raised in case of an error. On Windows, only the readonly flag is checked, every other permission is available in any case.

See also:

• setFilePermissions proc
• FilePermission enum

Source Edit

proc moveFile(source, dest: string) {....gcsafe, extern: "nos$1", tags: [
    ReadDirEffect, ReadIOEffect, WriteIOEffect], raises: [OSError], forbids: [].}

Moves a file from source to dest.

Symlinks are not followed: if source is a symlink, it is itself moved, not its target.

If this fails, OSError is raised. If dest already exists, it will be overwritten.

Can be used to rename files.

See also:

• osdirs: moveDir proc
• copyFile proc
• copyFileWithPermissions proc
• removeFile proc
• tryRemoveFile proc

Source Edit

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

Removes the file.

If this fails, OSError is raised. This does not fail if the file never existed in the first place.

On Windows, ignores the read-only attribute.

See also:

• osdirs: removeDir proc
• copyFile proc
• copyFileWithPermissions proc
• tryRemoveFile proc
• moveFile proc

Source Edit

proc setFilePermissions(filename: string; permissions: set[FilePermission];
                        followSymlinks = true) {....gcsafe, extern: "nos$1",
    tags: [ReadDirEffect, WriteDirEffect], raises: [OSError], forbids: [].}

Sets the file permissions for filename.

If followSymlinks set to true (default) and filename points to a symlink, permissions are set to the file symlink points to. followSymlinks set to false is a noop on Windows and some POSIX systems (including Linux) on which lchmod is either unavailable or always fails, given that symlinks permissions there are not observed.

OSError is raised in case of an error. On Windows, only the readonly flag is changed, depending on fpUserWrite permission.

See also:

• getFilePermissions proc
• FilePermission enum

Source Edit

proc tryRemoveFile(file: string): bool {....gcsafe, extern: "nos$1",
    tags: [WriteDirEffect], raises: [], forbids: [].}

Removes the file.

If this fails, returns false. This does not fail if the file never existed in the first place.

On Windows, ignores the read-only attribute.

See also:

• copyFile proc
• copyFileWithPermissions proc
• removeFile proc
• moveFile proc

Source Edit

Exports

fileExists