MAPMODE(3)                     Library Routines                     MAPMODE(3)

NAME

       _mapMode2GS,   _mapMode2Unix,  _getModeEmulation,  _setModeEmulation  -
       (mapMode) perform mappings between Unix and GS/OS file permissions.

SYNOPSIS

       #include <sys/types.h>
       #include <gno/gno.h>

       mode_t _mapMode2GS (mode_t mode);
       mode_t _mapMode2Unix (mode_t mode);
       int _getModeEmulation (void);
       int _setModeEmulation (int newval);

DESCRIPTION

       These routines are used to do mappings for  file  access  bits  between
       Unix and GS/OS file systems.

       Under  Unix,  the  lower  nine bits of a mode are broken into groups of
       three.  From most to least significant, these sets of  three  bits  are
       used for User, Group, and Other permissions.  Within each set, the bits
       refer to Read, Write, and Execute permissions.  Under GS/OS, each  file
       has associated with it bits for Read, Write, Invisible, Backup, Rename,
       and Destroy.

       By default, the system calls chmod(2),  creat(2),  and  open(2)  expect
       their  mode  parameters  to be Unix modes.  Before the underlying GS/OS
       toolset calls are made, these system calls therefore  do  mode  mapping
       via  the  _mapMode2GS  call.  (The system calls fstat(2), lstat(2), and
       stat(2) always return Unix modes in their st_mode fields).

       _mapMode2GS takes a Unix mode parameter and maps it the  GS/OS  equiva‐
       lent.  If the User Read bit is set in mode, the Read bit will be set in
       the result.  If the User Write bit is set in mode, all  of  the  Write,
       Rename,  and Destroy bits will be set in the result.  Regardless of the
       value of mode, the Invisible bit is always cleared and the  Backup  bit
       is always set.

       The  reverse mapping may be achieved through _mapMode2Unix.  This func‐
       tion takes a GS/OS mode parameter and maps it the Unix equivalent.   If
       the Read bit in mode is set, then the User, Group, and Others Read bits
       in the result will be set.  If all of the Write,  Rename,  and  Destroy
       bits  are  set in mode, then the User, Group and Others Write bits will
       be set in the result.  (If any of these three are  cleared,  the  Write
       bits  will  not be set.)  The result is bitwise ANDed with the umask(2)
       before _mapMode2Unix returns the value.  The high 7 bits (of 16) of the
       result are always cleared.




       There  are  times when it may be desirable to disable the mappings done
       by _mapMode2Unix  and  _mapMode2GS.   This  functionality  is  achieved
       through  the  _setModeEmulation  function.  If newval is zero, the mode
       mapping is turned off; the mapping functions act as null ops.  This im‐
       plies that the mode parameters of the above system calls will be inter‐
       preted as GS/OS modes, (see the CreatGS tool call in the  GS/OS  Refer���
       ence Manual).

       If a non-zero value is given for newval, the mode mapping functions are
       reactivated.

       _getModeEmulation  allows  the  application  programmer  to   determine
       whether or not the mapping functions are currently active.

COMPATIBILITY

       The  Orca/C  implementations  of chmod(2), creat(2), and open(2) expect
       GS/OS mode values, which is the opposite of the default for this imple‐
       mentation.

       _getModeEmulation,  _mapMode2Unix,  and  _mapMode2GS  are  thread safe.
       _setModeEmulation is not.

RETURN VALUE

       _getModeEmulation and _setModeEmulation return the current or  previous
       emulation value (zero or one), respectively.

       _mapMode2GS  and _mapMode2Unix return the appropriately mapped mode or,
       if mapping has been disabled, the original value of mode.

BUGS

       Since these routines don't known anything about file  systems,  nothing
       smart is done for permissions in an AppleShare environment.

       The  mappings  performed  by these routines are by their nature not en‐
       tirely reversable.

AUTHOR

       Devin Reade <gdr@gno.org>

SEE ALSO

       chmod(2), creat(2), open(2), stat(2), umask(2), The  Apple  IIgs  GS/OS
       Reference.



GNO                            14 December 1996                     MAPMODE(3)