vfsChangeOwner

function

Library: File system utilities (OMVFS legacy)
Include: omvfs.xin

Declaration

define external function vfsChangeOwner
                value string  path
      owner     value string  owner          (optional)
      group     value string  group          (optional)
      contents  value switch  contents       (optional)

or

define external function vfsChangeOwner
                value string  filename-URL
      on        value vfsDir  dir
      owner     value string  owner          (optional)
      group     value string  group          (optional)
      contents  value switch  contents       (optional)

Argument definitions

path: is the file or directory on which to change the group and/or owner.

filename-URL: is the name of the file or directory on which to change the group and/or owner expressed as a relative URL using the specified vfsDir as the base.

dir: is a vfsDir object created using either vfsConnect or vfsConnectDir.

owner: is the textual representation of the owner to be applied to the file or directory specified.

group: is the textual representation of the group to be applied to the file or directory specified.

contents: an options switch indicating if the ownership of the directory contents should also be modified. The default is that the directory contents are not to be modified. (VFS-NOT-INCLUDED)

Purpose

Use vfsChangeOwner to change a file's or directory's owner or group.

requirements

You must include the following line at the beginning of your OmniMark program:

  include "omvfs.xin"

path must:

exist (else external exception VFS306)
be a file or a directory
be expressed in local file system format as either
- an absolute path, or
- a path relative to the current working directory for the local file system

filename-URL must:

exist (else external exception VFS306)
be a file or a directory
be expressed as a relative URL based on the current working directory for dir (else external exception VFS105)

The vfsDir object dir must:

represent an existing connection made using vfsConnect or vfsConnectDir (else external exception VFS100)
represent a connection made using the File scheme (else external exception VFS001)

One of owner or group must be specified (else external exception VFS309)

The OmniMark program attempting to change the owner or group must have sufficient permissions to complete the operation (else external exception VFS310)

The operating system on which the OmniMark program is running must support ownership and group privileges (else external exception VFS308)

Usage Notes

On Windows, which has a notion of domains, the format for specifying owner and group is the domain followed by a backslash followed by the user or group, thus: "Domain\User".

If contents is set to VFS-INCLUDED and the target being modified is a directory then all the contents of the directory will also have the ownership change performed on them.

If the target being modified is a file then the value of contents is ignored.

External exception VFS111 is thrown if an URL supplied as a parameter to this function contains invalid encoding.

External exception VFS004 is thrown if the URL exceeds system length limits.

For complete details on absolute URLs and valid encoding, see Internet Standards RFC 1738: Uniform Resource Locators.

Example 1

Setting an owner and group of a file

  include "omvfs.xin"
  
  process
     vfsChangeOwner "afile.txt" owner "ftp" group "ftp"

Example 2

Setting an owner and group directory and all of its contents using Windows domain syntax

  include "omvfs.xin"
  
  process
     vfsChangeOwner "c:\some-dir" owner "Domain\ftp" group "Domain\ftp"
        contents VFS-INCLUDED

Other Library Functions