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 equivalent. 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 function 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 implies that the mode parameters of the above system calls will be interpreted as GS/OS modes, (see the CreatGS tool call in the GS/OS Reference 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 implementation.

_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 entirely reversable.

AUTHOR
Devin Reade <gdr@myrias.com>

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