FS_MakeDirectory

function

Library: File system utilities (OMFSYS legacy)
Include: omfsys.xin

Declaration
define external function FS_MakeDirectory
                value      stream  path
   with         value      integer mode
   status       modifiable stream  statusvalue

Argument definitions

path
contains the valid pathname of the new directory (input argument).
mode
is the desired permissions mode listed above for the new directory (input argument)
statusvalue
contains either a zero length string if the function succeeds, or one of the error codes listed above (output argument).


Purpose

The omfsys library has been deprecated and will be removed from a future version of the language. Use omvfs instead.

Use this function to create a new directory on a file system.

Requirements

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


  include "omfsys.xin"

Input arguments:

Output argument:

Usage Notes

You can use FS_MakeDirectory to allow or to restrict existing permissions, but never to expand them. This means you can create a directory with FS_MakeDirectory, but the permissions that FS_MakeDirectory assigns can only be those permissions or fewer that were inherited from the operating system.

Suppose, for the directory "C:\omprogs", you used Windows NT to assign read, write, and execute permissions to the creator and to groups, but assigned read-only permission to the category called "Everyone". Then suppose you used FS_MakeDirectory to create a directory called "cge_w-only" that gave only write privileges to the directory's creator, groups, and "Everyone". In Windows NT, the permissions are inherited from the parent directory. Since the parent directory has only read permission for creator, groups, and "Everyone", these two permission assignments are contradictory. What happens is that the operating system restricts the privileges -- the Windows NT restriction of read-only permission to "Everyone" will prevail. You will wind up with an effective mode of "224", not "222".

Examples

The program below will thus succeed in assigning write permission to the user and to the group, but permission for "Everyone" will disallow write access:

  include "omfsys.xin"
  
  process
    local stream a_status variable initial-size 1
  
    FS_MakeDirectory "C:\omprogs\abc" with 222 status a_status

Suppose you had a umask in UNIX that allowed all permissions to user and group and disallowed write permission for "other" (umask 002). Then suppose you used FS_MakeDirectory to assign write privileges to the file's owner, group, and "other". These two permission assignments are contradictory. What happens is that the operating system will restrict you -- the UNIX umask assignment of read-only permission to other will prevail. You will wind up with an effective mode of "220", not "222".

The program below will thus succeed in assigning write permissions to the owner and to the group, but permissions for "other" will not be set to anything:

  include "omfsys.xin"
  
  process
    local stream a_status variable initial-size 1
  
    FS_MakeDirectory "/home/bob/123/xyz" with 222 status a_status

Before you run this program, if your umask is 2 and you make a directory at the command line, for example "xyz", then by issuing ls -l , you will see the following:

   drwxrwxr-x   2 carl     carl         1024 Jul  19 11:13 xyz/

The 2 in your umask disallows write permission for "others". Now if you delete the directory you just made and run the program above, where you try to give the directory a mode of 222, you will create the directory, but with a mode of "220". When you again issue ls -l, you will see the following:

   d-w--w----   2 carl     carl         1024 Jul  19 11:13 xyz/

This is the expected behavior, as an OmniMark call should not exceed the permissions that the operating system assigns.

Related Topics