+-------------------------------------------------------------+

  #####                                                      
  #    # ##### ####  #   # #  ###   ###  #  ###  #    #  ### 
  #    # #     #   # ## ## # #     #     # #   # ##   # #    
  #####  ####  #   # # # # #  ###   ###  # #   # # #  #  ### 
  #      #     ####  #   # #     #     # # #   # #  # #     #
  #      #     #  #  #   # # #   # #   # # #   # #   ## #   #
  #      ##### #   # #   # #  ###   ###  #  ###  #    #  ### 

+-------------------------------------------------------------+
     
     
Summary:
========
     
    The SAGA API needs some meen to handle permissions to users
    and resources.  There multiple ways to specify such, e.g.
    as ACLs, as standard Unix permissions, or with a full blown
    authorization scheme.  As we are not aware of a appropriate
    _and_ simple standard for ACLs and authorization (on API
    level), unix permissions are adapted for simplicity, and
    extended by authorization hooks where necessary (e.g.
    streams).  That permission scheme might be changed in the
    future to adopt any emergin standard Grid permission API.

+-------------------------------------------------------------+

#ifndef SHORT

Use Cases:
==========

   TODO.
  
+-------------------------------------------------------------+

#endif

Specification:
==============

  package SAGA version 0.1 {
  
    package Permissions {

    enum permissionBits {

       U_RWX       0x700    // user (file owner) has read, write and execute permission
       U_READ      0x400    // user has read permission
       U_WRITE     0x200    // user has write permission
       U_EXECUTE   0x100    // user has execute permission

       G_RWX       0x070    // group has read, write and execute permission
       G_READ      0x040    // group has read permission
       G_WRITE     0x020    // group has write permission
       G_EXECUTE   0x010    // group has execute permission

       O_RWX       0x007    // others have read, write and execute permission
       O_READ      0x004    // others have read permission
       O_WRITE     0x002    // others have write permisson
       O_EXECUTE   0x001    // others have execute permission
      };

   
      enum permissionFlags {
        Recursive  =  1
      };
  
      interface Permissions {
  
        void set (in   int  perms, 
                  in   int  permissionFlags);
        void get (out  int  perms);
      }
    }
  } 

+-------------------------------------------------------------+

#ifndef SHORT

Details:
========


+-------------------------------------------------------------+


Examples:
=========

  TODO

+-------------------------------------------------------------+


Notes:
======


+-------------------------------------------------------------+

#endif // SHORT