[apple/xnu.git] / bsd / man / man2 / link.2

.\"	$NetBSD: link.2,v 1.7 1995/02/27 12:34:01 cgd Exp $
.\"
.\" Copyright (c) 1980, 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.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 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.
.\"
.\"     @(#)link.2	8.3 (Berkeley) 1/12/94
.\"
.Dd October 29, 2008
.Dt LINK 2
.Os BSD 4
.Sh NAME
.Nm link ,
.Nm linkat
.Nd make a hard file link
.Sh SYNOPSIS
.Fd #include <unistd.h>
.Ft int
.Fo link
.Fa "const char *path1"
.Fa "const char *path2"
.Fc
.Ft int
.Fo linkat
.Fa "int fd1" "const char *name1" "int fd2" "const char *name2" "int flag"
.Fc
.Sh DESCRIPTION
The
.Fn link
function call
atomically creates the specified directory entry (hard link)
.Fa path2
with the attributes of the underlying object pointed at by
.Fa path1 .
If the link is successful,
the link count of the underlying object is incremented;
.Fa path1
and
.Fa path2
share equal access and rights
to the
underlying object.
.Pp
If
.Fa path1
is removed, the file
.Fa path2
is not deleted and the link count of the
underlying object is
decremented.
.Pp
In order for the system call to succeed,
.Fa path1
must exist and both
.Fa path1
and
.Fa path2
must be in the same file system.
As mandated by POSIX.1,
.Fa path1
may not be a directory.
.Pp
.Fn link
will resolve and follow symbolic links contained within both
.Fa path1
and
.Fa path2 .
If the last component of
.Fa path1
is a symbolic link,
.Fn link
will point the hard link, 
.Fa path2 ,
to the underlying object pointed to by
.Fa path1 ,
not to the symbolic link itself.
.Pp
The
.Fn linkat
system call is equivalent to
.Fa link
except in the case where either
.Fa name1
or
.Fa name2
or both are relative paths.
In this case a relative path
.Fa name1
is interpreted relative to
the directory associated with the file descriptor
.Fa fd1
instead of the current working directory and similarly for
.Fa name2
and the file descriptor
.Fa fd2 .
.Pp
Values for
.Fa flag
are constructed by a bitwise-inclusive OR of flags from the following
list, defined in
.In fcntl.h :
.Bl -tag -width indent
.It Dv AT_SYMLINK_FOLLOW
If
.Fa name1
names a symbolic link, a new link for the target of the symbolic link is
created.
.El
.Pp
If
.Fn linkat
is passed the special value
.Dv AT_FDCWD
in the
.Fa fd1
or
.Fa fd2
parameter, the current working directory is used for the respective
.Fa name
argument.
If both
.Fa fd1
and
.Fa fd2
have value
.Dv AT_FDCWD ,
the behavior is identical to a call to
.Fn link .
Unless
.Fa flag
contains the
.Dv AT_SYMLINK_FOLLOW
flag, if
.Fa name1
names a symbolic link, a new link is created for the symbolic link
.Fa name1
and not its target. On OS X, not assigning AT_SYMLINK_FOLLOW to
.Fa flag
may result in some filesystems returning an error.
.Sh RETURN VALUES
Upon successful completion, a value of 0 is returned.  Otherwise,
a value of -1 is returned and
.Va errno
is set to indicate the error.
.Sh ERRORS
.Fn Link
will fail and no link will be created if:
.Bl -tag -width Er
.\" ==========
.It Bq Er EACCES
A component of either path prefix denies search permission.
.\" ==========
.It Bq Er EACCES
The requested link requires writing in a directory with a mode
that denies write permission.
.\" ==========
.It Bq Er EACCES
The current process cannot access the existing file.
.\" ==========
.It Bq Er EDQUOT
The directory in which the entry for the new link
is being placed cannot be extended because the
user's quota of disk blocks on the file system
containing the directory has been exhausted.
.\" ==========
.It Bq Er EEXIST
The link named by
.Fa path2
already exists.
.\" ==========
.It Bq Er EFAULT
One of the pathnames specified
is outside the process's allocated address space.
.\" ==========
.It Bq Er EIO
An I/O error occurs while reading from or writing to 
the file system to make the directory entry.
.\" ==========
.It Bq Er ELOOP
Too many symbolic links are encountered in translating one of the pathnames.
This is taken to be indicative of a looping symbolic link.
.\" ==========
.It Bq Er EMLINK
The file already has {LINK_MAX} links.
.\" ==========
.It Bq Er ENAMETOOLONG
A component of a pathname exceeds 
.Dv {NAME_MAX}
characters, or an entire path name exceeded 
.Dv {PATH_MAX}
characters.
.\" ==========
.It Bq Er ENOENT
A component of either path prefix does not exist, or is a dangling symbolic link.
.\" ==========
.It Bq Er ENOENT
The file named by
.Fa path1
does not exist, or is a dangling symbolic link.
.\" ==========
.It Bq Er ENOSPC
The directory in which the entry for the new link is being placed
cannot be extended because there is no space left on the file
system containing the directory.
.\" ==========
.It Bq Er ENOTDIR
A component of either path prefix is not a directory.
.\" ==========
.It Bq Er EPERM
The file named by
.Fa path1
is a directory.
.\" ==========
.It Bq Er EROFS
The requested link requires writing in a directory
on a read-only file system.
.\" ==========
.It Bq Er EXDEV
The link named by
.Fa path2
and the file named by
.Fa path1
are on different file systems.
.El
.Pp
In addition to the errors returned by the
.Fn link ,
the
.Fn linkat
system call may fail if:
.Bl -tag -width Er
.It Bq Er EBADF
The
.Fa name1
or
.Fa name2
argument does not specify an absolute path and the
.Fa fd1
or
.Fa fd2
argument, respectively, is neither
.Dv AT_FDCWD
nor a valid file descriptor open for searching.
.It Bq Er EINVAL
The value of the
.Fa flag
argument is not valid.
.It Bq Er ENOTSUP
.Fa flag
was not set to
.Dv AT_SYMLINK_FOLLOW (some filesystems only)
.It Bq Er ENOTDIR
The
.Fa name1
or
.Fa name2
argument is not an absolute path and
.Fa fd1
or
.Fa fd2 ,
respectively, is neither
.Dv AT_FDCWD
nor a file descriptor associated with a directory.
.El
.Sh SEE ALSO
.Xr symlink 2 ,
.Xr unlink 2
.Sh STANDARDS
The
.Fn link
function is expected to conform to 
.St -p1003.1-88 .
The
.Fn linkat
system call is expected to conform to POSIX.1-2008 .
Commit	Line	Data
9bccf70c A	1	.\" $NetBSD: link.2,v 1.7 1995/02/27 12:34:01 cgd Exp $
	2	.\"
	3	.\" Copyright (c) 1980, 1991, 1993
	4	.\" The Regents of the University of California. All rights reserved.
	5	.\"
	6	.\" Redistribution and use in source and binary forms, with or without
	7	.\" modification, are permitted provided that the following conditions
	8	.\" are met:
	9	.\" 1. Redistributions of source code must retain the above copyright
	10	.\" notice, this list of conditions and the following disclaimer.
	11	.\" 2. Redistributions in binary form must reproduce the above copyright
	12	.\" notice, this list of conditions and the following disclaimer in the
	13	.\" documentation and/or other materials provided with the distribution.
	14	.\" 3. All advertising materials mentioning features or use of this software
	15	.\" must display the following acknowledgement:
	16	.\" This product includes software developed by the University of
	17	.\" California, Berkeley and its contributors.
	18	.\" 4. Neither the name of the University nor the names of its contributors
	19	.\" may be used to endorse or promote products derived from this software
	20	.\" without specific prior written permission.
	21	.\"
	22	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	23	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	24	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	25	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	26	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	27	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	28	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	29	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	30	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	31	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	32	.\" SUCH DAMAGE.
	33	.\"
	34	.\" @(#)link.2 8.3 (Berkeley) 1/12/94
	35	.\"
b0d623f7	36	.Dd October 29, 2008
9bccf70c A	37	.Dt LINK 2
	38	.Os BSD 4
	39	.Sh NAME
fe8ab488 A	40	.Nm link ,
fe8ab488 A	41	.Nm linkat
9bccf70c A	42	.Nd make a hard file link
	43	.Sh SYNOPSIS
	44	.Fd #include <unistd.h>
	45	.Ft int
2d21ac55 A	46	.Fo link
	47	.Fa "const char *path1"
	48	.Fa "const char *path2"
	49	.Fc
fe8ab488 A	50	.Ft int
	51	.Fo linkat
	52	.Fa "int fd1" "const char name1" "int fd2" "const char name2" "int flag"
	53	.Fc
9bccf70c A	54	.Sh DESCRIPTION
	55	The
	56	.Fn link
	57	function call
	58	atomically creates the specified directory entry (hard link)
2d21ac55	59	.Fa path2
9bccf70c	60	with the attributes of the underlying object pointed at by
2d21ac55 A	61	.Fa path1 .
	62	If the link is successful,
	63	the link count of the underlying object is incremented;
	64	.Fa path1
9bccf70c	65	and
2d21ac55	66	.Fa path2
9bccf70c A	67	share equal access and rights
	68	to the
	69	underlying object.
	70	.Pp
	71	If
2d21ac55	72	.Fa path1
9bccf70c	73	is removed, the file
2d21ac55	74	.Fa path2
9bccf70c A	75	is not deleted and the link count of the
	76	underlying object is
	77	decremented.
	78	.Pp
2d21ac55 A	79	In order for the system call to succeed,
	80	.Fa path1
	81	must exist and both
	82	.Fa path1
9bccf70c	83	and
2d21ac55	84	.Fa path2
9bccf70c	85	must be in the same file system.
2d21ac55 A	86	As mandated by POSIX.1,
2d21ac55 A	87	.Fa path1
9bccf70c	88	may not be a directory.
b0d623f7 A	89	.Pp
	90	.Fn link
	91	will resolve and follow symbolic links contained within both
	92	.Fa path1
	93	and
	94	.Fa path2 .
	95	If the last component of
	96	.Fa path1
	97	is a symbolic link,
	98	.Fn link
	99	will point the hard link,
	100	.Fa path2 ,
	101	to the underlying object pointed to by
	102	.Fa path1 ,
	103	not to the symbolic link itself.
fe8ab488 A	104	.Pp
	105	The
	106	.Fn linkat
	107	system call is equivalent to
	108	.Fa link
	109	except in the case where either
	110	.Fa name1
	111	or
	112	.Fa name2
	113	or both are relative paths.
	114	In this case a relative path
	115	.Fa name1
	116	is interpreted relative to
	117	the directory associated with the file descriptor
	118	.Fa fd1
	119	instead of the current working directory and similarly for
	120	.Fa name2
	121	and the file descriptor
	122	.Fa fd2 .
	123	.Pp
	124	Values for
	125	.Fa flag
	126	are constructed by a bitwise-inclusive OR of flags from the following
	127	list, defined in
	128	.In fcntl.h :
	129	.Bl -tag -width indent
	130	.It Dv AT_SYMLINK_FOLLOW
	131	If
	132	.Fa name1
	133	names a symbolic link, a new link for the target of the symbolic link is
	134	created.
	135	.El
	136	.Pp
	137	If
	138	.Fn linkat
	139	is passed the special value
	140	.Dv AT_FDCWD
	141	in the
	142	.Fa fd1
	143	or
	144	.Fa fd2
	145	parameter, the current working directory is used for the respective
	146	.Fa name
	147	argument.
	148	If both
	149	.Fa fd1
	150	and
	151	.Fa fd2
	152	have value
	153	.Dv AT_FDCWD ,
	154	the behavior is identical to a call to
	155	.Fn link .
	156	Unless
	157	.Fa flag
	158	contains the
	159	.Dv AT_SYMLINK_FOLLOW
	160	flag, if
	161	.Fa name1
	162	names a symbolic link, a new link is created for the symbolic link
	163	.Fa name1
	164	and not its target. On OS X, not assigning AT_SYMLINK_FOLLOW to
	165	.Fa flag
	166	may result in some filesystems returning an error.
9bccf70c A	167	.Sh RETURN VALUES
	168	Upon successful completion, a value of 0 is returned. Otherwise,
	169	a value of -1 is returned and
	170	.Va errno
	171	is set to indicate the error.
	172	.Sh ERRORS
	173	.Fn Link
	174	will fail and no link will be created if:
	175	.Bl -tag -width Er
2d21ac55 A	176	.\" ==========
	177	.It Bq Er EACCES
	178	A component of either path prefix denies search permission.
	179	.\" ==========
	180	.It Bq Er EACCES
	181	The requested link requires writing in a directory with a mode
	182	that denies write permission.
	183	.\" ==========
	184	.It Bq Er EACCES
	185	The current process cannot access the existing file.
	186	.\" ==========
	187	.It Bq Er EDQUOT
	188	The directory in which the entry for the new link
	189	is being placed cannot be extended because the
	190	user's quota of disk blocks on the file system
	191	containing the directory has been exhausted.
	192	.\" ==========
	193	.It Bq Er EEXIST
	194	The link named by
	195	.Fa path2
	196	already exists.
	197	.\" ==========
	198	.It Bq Er EFAULT
	199	One of the pathnames specified
	200	is outside the process's allocated address space.
	201	.\" ==========
	202	.It Bq Er EIO
	203	An I/O error occurs while reading from or writing to
	204	the file system to make the directory entry.
	205	.\" ==========
	206	.It Bq Er ELOOP
	207	Too many symbolic links are encountered in translating one of the pathnames.
	208	This is taken to be indicative of a looping symbolic link.
	209	.\" ==========
	210	.It Bq Er EMLINK
	211	The file already has {LINK_MAX} links.
	212	.\" ==========
9bccf70c	213	.It Bq Er ENAMETOOLONG
2d21ac55	214	A component of a pathname exceeds
9bccf70c A	215	.Dv {NAME_MAX}
	216	characters, or an entire path name exceeded
	217	.Dv {PATH_MAX}
	218	characters.
2d21ac55	219	.\" ==========
9bccf70c	220	.It Bq Er ENOENT
b0d623f7	221	A component of either path prefix does not exist, or is a dangling symbolic link.
2d21ac55	222	.\" ==========
9bccf70c A	223	.It Bq Er ENOENT
9bccf70c A	224	The file named by
2d21ac55	225	.Fa path1
b0d623f7	226	does not exist, or is a dangling symbolic link.
2d21ac55 A	227	.\" ==========
	228	.It Bq Er ENOSPC
	229	The directory in which the entry for the new link is being placed
	230	cannot be extended because there is no space left on the file
	231	system containing the directory.
	232	.\" ==========
	233	.It Bq Er ENOTDIR
	234	A component of either path prefix is not a directory.
	235	.\" ==========
9bccf70c A	236	.It Bq Er EPERM
9bccf70c A	237	The file named by
2d21ac55	238	.Fa path1
9bccf70c	239	is a directory.
2d21ac55 A	240	.\" ==========
	241	.It Bq Er EROFS
	242	The requested link requires writing in a directory
	243	on a read-only file system.
	244	.\" ==========
9bccf70c A	245	.It Bq Er EXDEV
9bccf70c A	246	The link named by
2d21ac55	247	.Fa path2
9bccf70c	248	and the file named by
2d21ac55	249	.Fa path1
9bccf70c	250	are on different file systems.
9bccf70c	251	.El
fe8ab488 A	252	.Pp
	253	In addition to the errors returned by the
	254	.Fn link ,
	255	the
	256	.Fn linkat
	257	system call may fail if:
	258	.Bl -tag -width Er
	259	.It Bq Er EBADF
	260	The
	261	.Fa name1
	262	or
	263	.Fa name2
	264	argument does not specify an absolute path and the
	265	.Fa fd1
	266	or
	267	.Fa fd2
	268	argument, respectively, is neither
	269	.Dv AT_FDCWD
	270	nor a valid file descriptor open for searching.
	271	.It Bq Er EINVAL
	272	The value of the
	273	.Fa flag
	274	argument is not valid.
	275	.It Bq Er ENOTSUP
	276	.Fa flag
	277	was not set to
	278	.Dv AT_SYMLINK_FOLLOW (some filesystems only)
	279	.It Bq Er ENOTDIR
	280	The
	281	.Fa name1
	282	or
	283	.Fa name2
	284	argument is not an absolute path and
	285	.Fa fd1
	286	or
	287	.Fa fd2 ,
	288	respectively, is neither
	289	.Dv AT_FDCWD
	290	nor a file descriptor associated with a directory.
	291	.El
9bccf70c A	292	.Sh SEE ALSO
	293	.Xr symlink 2 ,
	294	.Xr unlink 2
	295	.Sh STANDARDS
	296	The
	297	.Fn link
	298	function is expected to conform to
	299	.St -p1003.1-88 .
fe8ab488 A	300	The
	301	.Fn linkat
	302	system call is expected to conform to POSIX.1-2008 .