gno/usr.man/man3/mapMode.3

.\" Man page by Devin Reade.
.\"
.\" $Id: mapMode.3,v 1.1 1997/02/27 07:32:23 gdr Exp $
.\"
.TH MAPMODE 3 "14 December 1996" GNO "Library Routines"
.SH NAME
.BR _mapMode2GS ,
.BR _mapMode2Unix ,
.BR _getModeEmulation ,
.BR _setModeEmulation
\- (mapMode) perform mappings between Unix and GS/OS file permissions.
.SH SYNOPSIS
#include <sys/types.h>
.br
#include <gno/gno.h>
.sp 1
mode_t
\fB_mapMode2GS\fR (mode_t \fImode\fR);
.br
mode_t
\fB_mapMode2Unix\fR (mode_t \fImode\fR);
.br
int 
\fB_getModeEmulation\fR (void);
.br
int 
\fB_setModeEmulation\fR (int \fInewval\fR);
.SH DESCRIPTION
These routines are used to do mappings for file access bits between
Unix and GS/OS file systems.
.LP
Under Unix, the lower nine bits of a 
.I 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.
.LP
By default, the system calls
.BR chmod (2),
.BR creat (2),
and
.BR 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
.BR _mapMode2GS
call.
(The system calls
.BR fstat (2),
.BR lstat (2),
and
.BR stat (2)
.IR always
return Unix modes in their 
.BR st_mode
fields).
.LP
.BR _mapMode2GS
takes a Unix
.I mode
parameter and maps it the GS/OS equivalent.  
If the User Read bit is set in
.IR mode ,
the Read bit will be set in the result.  If the User Write bit is set in
.IR mode ,
all of the Write, Rename, and Destroy bits will be set in the result.
Regardless of the value of 
.IR mode ,
the Invisible bit is always cleared and the Backup bit is always set.
.LP
The reverse mapping may be achieved through
.BR _mapMode2Unix .
This function takes a GS/OS
.I mode
parameter and maps it the Unix equivalent.
If the Read bit in
.IR 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 
.BR 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 
.IR AND ed
with the 
.BR umask (2)
before
.BR _mapMode2Unix
returns the value.  The high 7 bits (of 16) of the result are always cleared.



.LP
There are times when it may be desirable to disable the mappings done by
.BR _mapMode2Unix
and
.BR _mapMode2GS .
This functionality is achieved through the
.BR _setModeEmulation
function.  If
.IR 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
.BR CreatGS
tool call in the
.IR "GS/OS Reference Manual" ).
.LP
If a non-zero value is given for
.IR newval ,
the mode mapping functions are reactivated.
.LP
.BR _getModeEmulation
allows the application programmer to determine whether or not the 
mapping functions are currently active.
.SH COMPATIBILITY
The Orca/C implementations of
.BR chmod (2),
.BR creat (2),
and
.BR open (2)
expect GS/OS 
.IR mode
values, which is the opposite of the default for this implementation.
.LP
.BR _getModeEmulation ,
.BR _mapMode2Unix ,
and
.BR _mapMode2GS 
are thread safe.
.BR _setModeEmulation
is not.
.SH "RETURN VALUE"
.BR _getModeEmulation
and 
.BR _setModeEmulation
return the current or previous emulation value (zero or one), respectively.
.LP
.BR _mapMode2GS
and 
.BR _mapMode2Unix
return the appropriately mapped
.IR mode 
or, if mapping has been disabled, the original value of
.IR mode .
.SH BUGS
Since these routines don't known anything about file systems, nothing
smart is done for permissions in an AppleShare environment.
.LP
The mappings performed by these routines are by their nature not
entirely reversable.
.SH AUTHOR
Devin Reade <gdr@myrias.com>
.SH "SEE ALSO"
.BR chmod (2),
.BR creat (2),
.BR open (2),
.BR stat (2),
.BR umask (2),
.IR "The Apple IIgs GS/OS Reference" .