[apple/libc.git] / gen / FreeBSD / setmode.3

.\" Copyright (c) 1989, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)setmode.3	8.2 (Berkeley) 4/28/95
.\" $FreeBSD: src/lib/libc/gen/setmode.3,v 1.12 2007/01/09 00:27:55 imp Exp $
.\"
.Dd April 28, 1995
.Dt SETMODE 3
.Os
.Sh NAME
.Nm getmode ,
.Nm setmode
.Nd modify mode bits
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In unistd.h
.Ft mode_t
.Fn getmode "const void *set" "mode_t mode"
.Ft void *
.Fn setmode "const char *mode_str"
.Sh DESCRIPTION
The
.Fn getmode
function
returns a copy of the file permission bits
.Fa mode
as altered by the values pointed to by
.Fa set .
While only the mode bits are altered, other parts of the file mode
may be examined.
.Pp
The
.Fn setmode
function
takes an absolute (octal) or symbolic value, as described in
.Xr chmod 1 ,
as an argument
and returns a pointer to mode values to be supplied to
.Fn getmode .
Because some of the symbolic values are relative to the file
creation mask,
.Fn setmode
may call
.Xr umask 2 .
If this occurs, the file creation mask will be restored before
.Fn setmode
returns.
If the calling program changes the value of its file creation mask
after calling
.Fn setmode ,
.Fn setmode
must be called again if
.Fn getmode
is to modify future file modes correctly.
.Pp
If the mode passed to
.Fn setmode
is invalid or if memory cannot be allocated for the return value,
.Fn setmode
returns
.Dv NULL .
.Pp
The value returned from
.Fn setmode
is obtained from
.Fn malloc
and should be returned to the system with
.Fn free
when the program is done with it, generally after a call to
.Fn getmode .
.Sh ERRORS
The
.Fn setmode
function
may fail and set errno for any of the errors specified for the library
routine
.Xr malloc 3 .
.Sh SEE ALSO
.Xr chmod 1 ,
.Xr stat 2 ,
.Xr umask 2 ,
.Xr malloc 3
.Sh HISTORY
The
.Fn getmode
and
.Fn setmode
functions first appeared in
.Bx 4.4 .
Commit	Line	Data
5b2abdfb	1	.\" Copyright (c) 1989, 1991, 1993
e9ce8d39 A	2	.\" The Regents of the University of California. All rights reserved.
	3	.\"
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice, this list of conditions and the following disclaimer.
	9	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
e9ce8d39 A	12	.\" 4. Neither the name of the University nor the names of its contributors
	13	.\" may be used to endorse or promote products derived from this software
	14	.\" without specific prior written permission.
	15	.\"
	16	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	17	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	18	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	19	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	20	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	21	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	22	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	23	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	24	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	25	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	26	.\" SUCH DAMAGE.
	27	.\"
5b2abdfb	28	.\" @(#)setmode.3 8.2 (Berkeley) 4/28/95
1f2f436a	29	.\" $FreeBSD: src/lib/libc/gen/setmode.3,v 1.12 2007/01/09 00:27:55 imp Exp $
e9ce8d39	30	.\"
5b2abdfb A	31	.Dd April 28, 1995
5b2abdfb A	32	.Dt SETMODE 3
e9ce8d39 A	33	.Os
e9ce8d39 A	34	.Sh NAME
5b2abdfb A	35	.Nm getmode ,
	36	.Nm setmode
	37	.Nd modify mode bits
e9ce8d39 A	38	.Sh LIBRARY
	39	.Lb libc
	40	.Sh SYNOPSIS
5b2abdfb A	41	.In unistd.h
	42	.Ft mode_t
	43	.Fn getmode "const void *set" "mode_t mode"
	44	.Ft void *
	45	.Fn setmode "const char *mode_str"
e9ce8d39 A	46	.Sh DESCRIPTION
e9ce8d39 A	47	The
5b2abdfb A	48	.Fn getmode
	49	function
	50	returns a copy of the file permission bits
	51	.Fa mode
	52	as altered by the values pointed to by
	53	.Fa set .
	54	While only the mode bits are altered, other parts of the file mode
	55	may be examined.
	56	.Pp
e9ce8d39	57	The
5b2abdfb A	58	.Fn setmode
	59	function
	60	takes an absolute (octal) or symbolic value, as described in
	61	.Xr chmod 1 ,
	62	as an argument
	63	and returns a pointer to mode values to be supplied to
	64	.Fn getmode .
	65	Because some of the symbolic values are relative to the file
	66	creation mask,
	67	.Fn setmode
	68	may call
	69	.Xr umask 2 .
	70	If this occurs, the file creation mask will be restored before
	71	.Fn setmode
	72	returns.
	73	If the calling program changes the value of its file creation mask
	74	after calling
	75	.Fn setmode ,
	76	.Fn setmode
	77	must be called again if
	78	.Fn getmode
	79	is to modify future file modes correctly.
	80	.Pp
	81	If the mode passed to
	82	.Fn setmode
	83	is invalid or if memory cannot be allocated for the return value,
	84	.Fn setmode
	85	returns
	86	.Dv NULL .
	87	.Pp
	88	The value returned from
	89	.Fn setmode
	90	is obtained from
	91	.Fn malloc
	92	and should be returned to the system with
	93	.Fn free
	94	when the program is done with it, generally after a call to
	95	.Fn getmode .
e9ce8d39	96	.Sh ERRORS
5b2abdfb A	97	The
	98	.Fn setmode
	99	function
	100	may fail and set errno for any of the errors specified for the library
	101	routine
	102	.Xr malloc 3 .
e9ce8d39	103	.Sh SEE ALSO
5b2abdfb A	104	.Xr chmod 1 ,
	105	.Xr stat 2 ,
	106	.Xr umask 2 ,
	107	.Xr malloc 3
e9ce8d39 A	108	.Sh HISTORY
e9ce8d39 A	109	The
5b2abdfb A	110	.Fn getmode
	111	and
	112	.Fn setmode
	113	functions first appeared in
e9ce8d39	114	.Bx 4.4 .