1.\" Copyright (c) 2003 Apple Computer, Inc. All rights reserved. 2.\" 3.\" The contents of this file constitute Original Code as defined in and 4.\" are subject to the Apple Public Source License Version 1.1 (the 5.\" "License"). You may not use this file except in compliance with the 6.\" License. Please obtain a copy of the License at 7.\" http://www.apple.com/publicsource and read it before using this file. 8.\" 9.\" This Original Code and all software distributed under the License are 10.\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER 11.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 12.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 13.\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the 14.\" License for the specific language governing rights and limitations 15.\" under the License. 16.\" 17.\" @(#)exchangedata.2 18. 19.Dd December 15, 2003 20.Dt EXCHANGEDATA 2 21.Os Darwin 22.Sh NAME 23.Nm exchangedata 24.Nd atomically exchange data between two files 25.Sh SYNOPSIS 26.Fd #include <unistd.h> 27.Fd #include <sys/attr.h> 28.Ft int 29.Fn exchangedata "const char * path1" "const char * path2" "unsigned int options" 30. 31.Sh DESCRIPTION 32The 33.Fn exchangedata 34function swaps the contents of the files referenced by 35.Fa path1 36and 37.Fa path2 38in an atomic fashion. 39That is, all concurrent processes will either see the pre-exchanged state or the 40post-exchanged state; they can never see the files in an inconsistent state. 41The data in all forks is swapped in this way. 42The 43.Fa options 44parameter lets you control specific aspects of the function's behaviour. 45.Pp 46. 47Open file descriptors follow the swapped data. 48Thus, a descriptor that previously referenced 49.Fa path1 50will now reference the data that's accessible via 51.Fa path2 , 52and vice versa. 53.Pp 54. 55In general, the file attributes (metadata) are not exchanged. 56Specifically, the object identifier attributes (that is, the 57.Dv ATTR_CMN_OBJID 58and 59.Dv ATTR_CMN_OBJPERMANENTID 60attributes as defined by the 61.Xr getattrlist 2 62function) are not swapped. 63An exception to this general rule is that the modification time attribute ( 64.Dv ATTR_CMN_MODTIME 65) is swapped. 66.Pp 67. 68When combined, these features allow you to implement a 'safe save' function that 69does not break references to the file (for example, aliases). 70You first save the new contents to a temporary file and then 71exchange the data of the original file and the temporary. 72Programs that reference the file via an object identifier will continue to 73reference the original file, but now it has the new data. 74.Pp 75. 76WARNING: This system call is largely supported only by HFS and AFP file systems. Many other 77file systems, including APFS, do not support it. Further, it is not supported on iOS, tvOS, or watchOS. 78It is recommended that callers refer 79instead to 80.Fn rename 81or 82.Fn renamex_np 83to conduct safe-save operations instead. 84.Pp 85. 86.\" path1 and path2 parameters 87. 88The 89.Fa path1 90and 91.Fa path2 92parameters must both reference valid files. 93All directories listed in the path names leading to these files must be 94searchable. 95You must have write access to the files. 96.Pp 97. 98.\" options parameter 99. 100The 101.Fa options 102parameter is a bit set that controls the behaviour of 103.Fn exchangedata . 104The following option bits are defined. 105. 106.Bl -tag -width FSOPT_NOFOLLOW 107. 108.It FSOPT_NOFOLLOW 109If this bit is set, 110.Fn exchangedata 111will not follow a symlink if it occurs as 112the last component of 113.Fa path1 114or 115.Fa path2 . 116. 117.El 118. 119.Sh RETURN VALUES 120Upon successful completion a value of 0 is returned. 121Otherwise, a value of -1 is returned and 122.Va errno 123is set to indicate the error. 124. 125.Sh COMPATIBILITY 126Not all volumes support 127.Fn exchangedata . 128This includes APFS volumes. 129You can test whether a volume supports 130.Fn exchangedata 131by using 132.Xr getattrlist 2 133to get the volume capabilities attribute 134.Dv ATTR_VOL_CAPABILITIES , 135and then testing the 136.Dv VOL_CAP_INT_EXCHANGEDATA 137flag. 138.Pp 139. 140.Sh ERRORS 141.Fn exchangedata 142will fail if: 143.Bl -tag -width Er 144. 145.It Bq Er ENOTSUP 146The volume does not support 147.Fn exchangedata . 148. 149.It Bq Er ENOTDIR 150A component of the path prefix is not a directory. 151. 152.It Bq Er ENAMETOOLONG 153A component of a path name exceeded 154.Dv NAME_MAX 155characters, or an entire path name exceeded 156.Dv PATH_MAX 157characters. 158. 159.It Bq Er ENOENT 160Either file does not exist. 161. 162.It Bq Er EACCES 163Search permission is denied for a component of the path prefix. 164. 165.It Bq Er ELOOP 166Too many symbolic links were encountered in translating the pathname. 167. 168.It Bq Er EFAULT 169.Fa path1 170or 171.Em path2 172points to an invalid address. 173. 174.It Bq Er EXDEV 175.Fa path1 176and 177.Em path2 178are on different volumes (mounted file systems). 179. 180.It Bq Er EINVAL 181.Fa path1 182or 183.Em path2 184reference the same file. 185. 186.It Bq Er EINVAL 187You try to exchange something other than a regular file (for example, a directory). 188. 189.It Bq Er EIO 190An I/O error occurred while reading from or writing to the file system. 191.El 192.Pp 193. 194.Sh SEE ALSO 195. 196.Xr getattrlist 2 , 197.Xr rename 2 198. 199.Sh HISTORY 200A 201.Fn exchangedata 202function call appeared in Darwin 1.3.1 (Mac OS X version 10.0). 203. 204It was deprecated in macOS 10.13. 205