git.saurik.com Git - apple/xnu.git/blame_incremental

... / ...

Commit	Line	Data
	1	.\" Copyright (c) 1980, 1991, 1993, 1994
	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.
	12	.\" 3. All advertising materials mentioning features or use of this software
	13	.\" must display the following acknowledgement:
	14	.\" This product includes software developed by the University of
	15	.\" California, Berkeley and its contributors.
	16	.\" 4. Neither the name of the University nor the names of its contributors
	17	.\" may be used to endorse or promote products derived from this software
	18	.\" without specific prior written permission.
	19	.\"
	20	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	21	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	22	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	23	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	24	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	25	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	26	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	27	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	28	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	29	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	30	.\" SUCH DAMAGE.
	31	.\"
	32	.\" @(#)chown.2 8.4 (Berkeley) 4/19/94
	33	.\"
	34	.Dd April 19, 1994
	35	.Dt CHOWN 2
	36	.Os
	37	.Sh NAME
	38	.Nm chown ,
	39	.Nm fchown ,
	40	.Nm lchown
	41	.Nd change owner and group of a file
	42	.Sh SYNOPSIS
	43	.In unistd.h
	44	.Ft int
	45	.Fn chown "const char *path" "uid_t owner" "gid_t group"
	46	.Ft int
	47	.Fn fchown "int fd" "uid_t owner" "gid_t group"
	48	.Ft int
	49	.Fn lchown "const char *path" "uid_t owner" "gid_t group"
	50	.Sh DESCRIPTION
	51	The owner ID and group ID of the file
	52	named by
	53	.Fa path
	54	or referenced by
	55	.Fa fd
	56	is changed as specified by the arguments
	57	.Fa owner
	58	and
	59	.Fa group .
	60	The owner of a file may change the
	61	.Fa group
	62	to a group of which
	63	he or she is a member,
	64	but the change
	65	.Fa owner
	66	capability is restricted to the super-user.
	67	.Pp
	68	The
	69	.Fn chown
	70	system call
	71	clears the set-user-id and set-group-id bits
	72	on the file
	73	to prevent accidental or mischievous creation of
	74	set-user-id and set-group-id programs if not executed
	75	by the super-user.
	76	The
	77	.Fn chown
	78	system call
	79	follows symbolic links to operate on the target of the link
	80	rather than the link itself.
	81	.Pp
	82	The
	83	.Fn fchown
	84	system call
	85	is particularly useful when used in conjunction
	86	with the file locking primitives (see
	87	.Xr flock 2 ) .
	88	.Pp
	89	The
	90	.Fn lchown
	91	system call is similar to
	92	.Fn chown
	93	but does not follow symbolic links.
	94	.Pp
	95	One of the owner or group id's
	96	may be left unchanged by specifying it as -1.
	97	.Sh RETURN VALUES
	98	.Rv -std
	99	.Sh ERRORS
	100	The
	101	.Fn chown
	102	and
	103	.Fn lchown
	104	will fail and the file will be unchanged if:
	105	.Bl -tag -width Er
	106	.It Bq Er ENOTDIR
	107	A component of the path prefix is not a directory.
	108	.It Bq Er ENAMETOOLONG
	109	A component of a pathname exceeded 255 characters,
	110	or an entire path name exceeded 1023 characters.
	111	.It Bq Er ENOENT
	112	The named file does not exist.
	113	.It Bq Er EACCES
	114	Search permission is denied for a component of the path prefix.
	115	.It Bq Er ELOOP
	116	Too many symbolic links were encountered in translating the pathname.
	117	.It Bq Er EPERM
	118	The effective user ID is not the super-user.
	119	.It Bq Er EROFS
	120	The named file resides on a read-only file system.
	121	.It Bq Er EFAULT
	122	The
	123	.Fa path
	124	argument
	125	points outside the process's allocated address space.
	126	.It Bq Er EIO
	127	An I/O error occurred while reading from or writing to the file system.
	128	.El
	129	.Pp
	130	The
	131	.Fn fchown
	132	system call will fail if:
	133	.Bl -tag -width Er
	134	.It Bq Er EBADF
	135	The
	136	.Fa fd
	137	argument
	138	does not refer to a valid descriptor.
	139	.It Bq Er EINVAL
	140	The
	141	.Fa fd
	142	argument
	143	refers to a socket, not a file.
	144	.It Bq Er EPERM
	145	The effective user ID is not the super-user.
	146	.It Bq Er EROFS
	147	The named file resides on a read-only file system.
	148	.It Bq Er EIO
	149	An I/O error occurred while reading from or writing to the file system.
	150	.El
	151	.Sh SEE ALSO
	152	.Xr chgrp 1 ,
	153	.Xr chmod 2 ,
	154	.Xr flock 2 ,
	155	.Xr chown 8
	156	.Sh STANDARDS
	157	The
	158	.Fn chown
	159	system call is expected to conform to
	160	.St -p1003.1-90 .
	161	.Sh HISTORY
	162	The
	163	.Fn chown
	164	function appeared in
	165	.At v7 .
	166	The
	167	.Fn fchown
	168	system call appeared in
	169	.Bx 4.2 .
	170	.Pp
	171	The
	172	.Fn chown
	173	and
	174	.Fn fchown
	175	system calls were changed to follow symbolic links in
	176	.Bx 4.4 .
	177	The
	178	.Fn lchown
	179	system call was added in
	180	.Fx 3.0
	181	to compensate for the loss of functionality.