darling-removefile/removefile.3

.\" Copyright (c) 2015 Apple Inc.
.\" 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 April 1, 2020
.Dt REMOVEFILE 3
.Os
.Sh NAME
.Nm removefile , removefileat , removefile_state_alloc ,
.Nm removefile_state_free , removefile_state_get ,
.Nm removefile_state_set
.Nd remove files or directories
.Sh SYNOPSIS
.In removefile.h
.Ft int
.Fn removefile "const char *path" "removefile_state_t state" "removefile_flags_t flags"
.Ft int
.Fn removefileat "int fd" "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
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.
.Pp
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.
.Pp
The
.Fn removefileat
function is equivalent to the
.Fn removefile
function except in the case where the
.Va path
specifies a relative path.
In that case the file to be removed is determined relative to the directory associated with the file descriptor
.Va fd
instead of the current working directory.
If the special value AT_FDCWD is passed in the
.Va fd
argument, the current working directory is used and the behavior is identical to a call to
.Fn removefile.
.Pp
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:
.Bl -tag -width REMOVEFILE_SECURE_1_PASS_ZERO
.It Dv REMOVEFILE_RECURSIVE
If the 
.Va path
location is a directory, then recursively delete the entire directory.
.It 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.
.It Dv REMOVEFILE_CROSS_MOUNT
By default, recursive traversals do not cross mount points.
This option allows
.Fn removefile
to descend into directories that have a different device number than the file from which
the descent began.
.It Dv REMOVEFILE_SECURE_7_PASS
Overwrite the file with 7 US DoD compliant passes (0xF6, 0x00,  0xFF,  random, 0x00, 0xFF, random).
.It Dv REMOVEFILE_SECURE_35_PASS
Overwrite the file using 35-pass Gutmann algorithm.
.It Dv REMOVEFILE_SECURE_3_PASS
Overwrite the file twice with random bytes, and then with 0xAA.
.It Dv REMOVEFILE_SECURE_1_PASS
Overwrite with a single pass of random data.
.It Dv REMOVEFILE_SECURE_1_PASS_ZERO
Overwrite with a single pass of zeroes.
.El
.Pp
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.
.Bl -tag -width REMOVEFILE_STATE_CONFIRM_CALLBACK
.It Dv REMOVEFILE_STATE_CONFIRM_CALLBACK
Get or set the callback function of type 
.Va removefile_callback_t
to be called prior to file deletion.
.It Dv REMOVEFILE_STATE_CONFIRM_CONTEXT
Get or set any parameters of type
.Va void *
that are needed for the confirm callback function.
.It 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.
.It Dv REMOVEFILE_STATE_ERROR_CONTEXT
Get or set any parameters of type
.Va void *
that are needed for the error callback function.
.It Dv REMOVEFILE_STATE_ERRNO
Get or set the current errno of type
.Va int
.It Dv REMOVEFILE_STATE_STATUS_CALLBACK
Get or set the callback function of type 
.Va removefile_callback_t
to be called subsequent to file deletion.
.It Dv REMOVEFILE_STATE_STATUS_CONTEXT
Get or set any parameters of type
.Va void *
that are needed for the status callback function.
.El
.Pp
The 
.Va removefile_callback_t
function pointer is defined as the following:
.Pp
.Ft int
.Va (*removefile_callback_t) (removefile_state_t state, const char *path , void *context)
.Pp
The return value of the callback function is given as:
.Bl -tag -width REMOVEFILE_PROCEED
.It Dv REMOVEFILE_PROCEED
File is deleted and 
.Fn removefile
continues operation as normal.
.It Dv REMOVEFILE_SKIP
Current file is not deleted and
.Fn removefile
continues operation as normal.
.It Dv REMOVEFILE_STOP
Current file is not deleted and 
.Fn removefile
exits without continuing further.
.El
.Pp
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:
.Bl -tag -width Er
.It Bq Er EACCES
The 
.Va path
location specifies a file or directory for which the calling process does not
have proper permissions.
.It Bq Er EINVAL
A callback returned an invalid return value (not REMOVEFILE_PROCEED, REMOVEFILE_SKIP, or REMOVEFILE_STOP)
.It Bq Er EMLINK
The 
.Va path
location refers to a symbolic link.
.It Bq Er ENAMETOOLONG
The resource fork name of the file exceeds the maximum allowed length.
.It Bq Er ENOMEM
A memory allocation failed.
.It Bq Er ENOTEMPTY
The 
.Va path
location specifies a directory that contains an immutable file which cannot be
deleted.
.It Bq Er EPERM
The 
.Va path
location specifies an immutable file that cannot be deleted.
.El
.Pp
.Fn removefile_cancel
will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
A
.Va NULL
parameter was passed into
.Fn removefile_cancel .
.El
.Pp
In addition, all functions may return an error from an underlying library or
system call.
.Sh NOTES
Write protected files owned by another user cannot be removed by
.Fn removefile , 
regardless of the permissions on the directory containing the file.
.Pp
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.
.Pp
.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.
.Pp
.Fn removefile
operates on symbolic links, rather than the target of the link.
.Sh EXAMPLE
.Bd -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);
.Pp
/* 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 unlink 1 ,
.Xr sync 2 ,
.Xr sync_volume_np 3
.Sh HISTORY
The
.Fn removefile
API was introduced in Mac OS X 10.5.