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. Neither the name of Apple Inc. ("Apple") 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 APPLE AND ITS 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 APPLE OR ITS 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.
.Dd May 4, 2007 .Dt REMOVEFILE 3 .Os .Sh NAME .Nm removefile , removefile_state_alloc , .Nm removefile_state_free , removefile_state_get , .Nm removefile_state_set .Nd remove files or directories .Sh SYNOPSIS n removefile.h .Ft int .Fn removefile "const char *path" "removefile_state_t state" "removefile_flags_t flags" .Ft removefile_state_t .Fn removefile_state_alloc "void" .Ft int .Fn removefile_state_free "removefile_state_t state" .Ft int .Fn removefile_state_get "removefile_state_t state" "uint32_t key" "void * dst" .Ft int .Fn removefile_state_set "removefile_state_t state" "uint32_t key" "const void * value" .Ft int .Fn removefile_cancel "removefile_state_t state" .Sh DESCRIPTION
p These functions are used to remove a file or directory. Various levels of overwriting may be specified to prevent other people from recovering any information about the file.
p The .Fn removefile_state_alloc function initializes a .Vt removefile_state_t object (which is an opaque data type). This object can be passed to .Fn removefile . .Fn removefile_state_get and .Fn removefile_state_set can be used to manipulate the state (see below). The .Fn removefile_state_free function is used to deallocate the object and its contents.
p The .Fn removefile function removes files and directories located at the named .Va path filesystem location. The named .Va path location can be specified as either an absolute path or relative to the working directory of the calling process. If the .Va state parameter is the return value from .Fn removefile_state_alloc , then .Fn removefile will use the information from the state object; if it is .Dv NULL , then .Fn removefile will work normally, but less control will be available to the caller. The .Va flags parameter controls deletion options: l -tag -width REMOVEFILE_SECURE_1_PASS_ZERO t Dv REMOVEFILE_RECURSIVE If the .Va path location is a directory, then recursively delete the entire directory. t Dv REMOVEFILE_KEEP_PARENT The file or directory at the .Va path location is not deleted. If specified in conjunction with REMOVEFILE_RECURSIVE, then all of the contents of the directory at .Va path location will be deleted, but not the directory itself. t Dv REMOVEFILE_SECURE_7_PASS Overwrite the file with 7 US DoD compliant passes (0xF6, 0x00, 0xFF, random, 0x00, 0xFF, random). t Dv REMOVEFILE_SECURE_35_PASS Overwrite the file using 35-pass Gutmann algorithm. t Dv REMOVEFILE_SECURE_3_PASS Overwrite the file twice with random bytes, and then with 0xAA. t Dv REMOVEFILE_SECURE_1_PASS Overwrite with a single pass of random data. t Dv REMOVEFILE_SECURE_1_PASS_ZERO Overwrite with a single pass of zeroes. .El
p The .Fn removefile_state_get and .Fn removefile_state_set functions can be used to manipulate the .Ft removefile_state_t object returned by .Fn removefile_state_alloc . In both functions, the .Va dst or the .Va value parameter's type depends on the .Va key parameter that is passed in. l -tag -width REMOVEFILE_STATE_CONFIRM_CALLBACK t Dv REMOVEFILE_STATE_CONFIRM_CALLBACK Get or set the callback function of type .Va removefile_callback_t to be called prior to file deletion. t Dv REMOVEFILE_STATE_CONFIRM_CONTEXT Get or set any parameters of type .Va void * that are needed for the confirm callback function. t Dv REMOVEFILE_STATE_ERROR_CALLBACK Get or set the callback function of type .Va removefile_callback_t to be called when an error is detected. t Dv REMOVEFILE_STATE_ERROR_CONTEXT Get or set any parameters of type .Va void * that are needed for the error callback function. t Dv REMOVEFILE_STATE_ERRNO Get or set the current errno of type .Va int t Dv REMOVEFILE_STATE_STATUS_CALLBACK Get or set the callback function of type .Va removefile_callback_t to be called subsequent to file deletion. t Dv REMOVEFILE_STATE_STATUS_CONTEXT Get or set any parameters of type .Va void * that are needed for the status callback function. .El
p The .Va removefile_callback_t function pointer is defined as the following:
p .Ft int .Va (*removefile_callback_t) (removefile_state_t state, const char *path , void *context)
p The return value of the callback function is given as: l -tag -width REMOVEFILE_PROCEED t Dv REMOVEFILE_PROCEED File is deleted and .Fn removefile continues operation as normal. t Dv REMOVEFILE_SKIP Current file is not deleted and .Fn removefile continues operation as normal. t Dv REMOVEFILE_STOP Current file is not deleted and .Fn removefile exits without continuing further. .El
p The .Fn removefile_cancel function is used to cancel a remove that is in progress. .Sh RETURN VALUES The family of .Fn removefile functions returns less than 0 on error, and 0 on success. .Sh ERRORS .Fn removefile will fail if: l -tag -width Er t Bq Er EACCES The .Va path location specifies a file or directory for which the calling process does not have proper permissions. t Bq Er EINVAL A callback returned an invalid return value (not REMOVEFILE_PROCEED, REMOVEFILE_SKIP, or REMOVEFILE_STOP) t Bq Er EMLINK The .Va path location refers to a symbolic link. t Bq Er ENAMETOOLONG The resource fork name of the file exceeds the maximum allowed length. t Bq Er ENOMEM A memory allocation failed. t Bq Er ENOTEMPTY The .Va path location specifies a directory that contains an immutable file which cannot be deleted. t Bq Er EPERM The .Va path location specifies an immutable file that cannot be deleted. .El
p .Fn removefile_cancel will fail if: l -tag -width Er t Bq Er EINVAL A .Va NULL parameter was passed into .Fn removefile_cancel . .El
p In addition, all functions may return an error from an underlying library or system call. .Sh NOTES
p Write protected files owned by another user cannot be removed by .Fn removefile , regardless of the permissions on the directory containing the file.
p If multiple of the REMOVEFILE_SECURE_1_PASS, REMOVEFILE_SECURE_7_PASS, and REMOVEFILE_SECURE_35_PASS flags are specified, .Fn removefile will proceed using the flag that specifies the highest number of overwriting passes.
p .Fn removefile is pathname-based; this means that, when descending into a hierarchy, there are potential race conditions that may add risk when run with privileges.
p .Fn removefile operates on symbolic links, rather than the target of the link. .Sh EXAMPLES d -literal -offset indent /* Initialize a state variable */ removefile_state_t s; s = removefile_state_alloc(); /* Recursively remove all files and directories while keeping parent tmp directory. */ removefile("/tmp", s, REMOVEFILE_RECURSIVE | REMOVEFILE_KEEP_PARENT); /* Release the state variable */ removefile_state_free(s);
p /* A more complex way to call removefile() -- define a callback function */ int removefile_status_callback(removefile_state_t state, const char * path, void * context) { fprintf(stderr, "File deleted: %s", path); return REMOVEFILE_PROCEED; } /* Initialize a state variable */ s = removefile_state_alloc(); /* Set callback function properties */ removefile_state_set(s, REMOVEFILE_STATE_CONFIRM_CALLBACK, removefile_confirm_callback); removefile_state_set(s, REMOVEFILE_STATE_CONFIRM_CONTEXT, NULL); /* Recursively remove all files and directories while keeping parent tmp directory, calling a confirm callback prior to each file deletion. */ removefile("/tmp", s, REMOVEFILE_RECURSIVE | REMOVEFILE_KEEP_PARENT); /* Release the state variable. */ removefile_state_free(s); .Ed .Sh "SEE ALSO" .Xr srm 1 , .Xr unlink 1 , .Xr sync 2 , .Xr sync_volume_np 3 .Sh HISTORY The .Fn removefile API was introduced in Mac OS X 10.5.