REMOVEFILE(3) | Library Functions Manual | REMOVEFILE(3) |
removefile
,
removefileat
,
removefile_state_alloc
,
removefile_state_free
,
removefile_state_get
,
removefile_state_set
—
remove files or directories
#include
<removefile.h>
int
removefile
(const
char *path,
removefile_state_t state,
removefile_flags_t
flags);
int
removefileat
(int
fd, const char
*path, removefile_state_t
state, removefile_flags_t
flags);
removefile_state_t
removefile_state_alloc
(void);
int
removefile_state_free
(removefile_state_t
state);
int
removefile_state_get
(removefile_state_t
state, uint32_t
key, void *
dst);
int
removefile_state_set
(removefile_state_t
state, uint32_t
key, const void *
value);
int
removefile_cancel
(removefile_state_t
state);
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.
The
removefile_state_alloc
()
function initializes a removefile_state_t object
(which is an opaque data type). This object can be passed to
removefile
().
removefile_state_get
() and
removefile_state_set
() can be used to manipulate the
state (see below). The
removefile_state_free
()
function is used to deallocate the object and its contents.
The
removefileat
()
function is equivalent to the removefile
() function
except in the case where the path specifies a relative
path. In that case the file to be removed is determined relative to the
directory associated with the file descriptor fd
instead of the current working directory. If the special value AT_FDCWD is
passed in the fd argument, the current working
directory is used and the behavior is identical to a call to
removefile
().
The
removefile
()
function removes files and directories located at the named
path filesystem location. The named
path location can be specified as either an absolute
path or relative to the working directory of the calling process. If the
state parameter is the return value from
removefile_state_alloc
(), then
removefile
() will use the information from the state
object; if it is NULL
, then
removefile
() will work normally, but less control
will be available to the caller. The flags parameter
controls deletion options:
REMOVEFILE_RECURSIVE
REMOVEFILE_KEEP_PARENT
REMOVEFILE_CROSS_MOUNT
removefile
() to descend into directories
that have a different device number than the file from which the descent
began.REMOVEFILE_SECURE_7_PASS
REMOVEFILE_SECURE_35_PASS
REMOVEFILE_SECURE_3_PASS
REMOVEFILE_SECURE_1_PASS
REMOVEFILE_SECURE_1_PASS_ZERO
REMOVEFILE_ALLOW_LONG_PATHS
removefile
() temporarily. (This does not
remove the requirement that no component of the path
location exceeds NAME_MAX characters, nor does it allow the
path argument itself to exceed PATH_MAX.)The
removefile_state_get
()
and
removefile_state_set
()
functions can be used to manipulate the
removefile_state_t object returned by
removefile_state_alloc
(). In both functions, the
dst or the value parameter's
type depends on the key parameter that is passed
in.
REMOVEFILE_STATE_CONFIRM_CALLBACK
REMOVEFILE_STATE_CONFIRM_CONTEXT
REMOVEFILE_STATE_ERROR_CALLBACK
REMOVEFILE_STATE_ERROR_CONTEXT
REMOVEFILE_STATE_ERRNO
REMOVEFILE_STATE_STATUS_CALLBACK
REMOVEFILE_STATE_STATUS_CONTEXT
The removefile_callback_t function pointer is defined as the following:
int (*removefile_callback_t) (removefile_state_t state, const char *path, void *context)
The return value of the callback function is given as:
REMOVEFILE_PROCEED
removefile
()
continues operation as normal.REMOVEFILE_SKIP
removefile
()
continues operation as normal.REMOVEFILE_STOP
removefile
() exits
without continuing further.The
removefile_cancel
()
function is used to cancel a remove that is in progress.
The family of removefile
() functions
returns less than 0 on error, and 0 on success.
removefile
() will fail if:
EACCES
]EINVAL
]EMLINK
]ENAMETOOLONG
]ENOMEM
]ENOTEMPTY
]EPERM
]removefileat
() will fail if:
ENOTDIR
]removefile_cancel
() will fail if:
EINVAL
]removefile_cancel
().In addition, all functions may return an error from an underlying library or system call.
Write protected files owned by another user cannot be removed by
removefile
(),
regardless of the permissions on the directory containing the file.
If multiple of the REMOVEFILE_SECURE_1_PASS,
REMOVEFILE_SECURE_7_PASS, and REMOVEFILE_SECURE_35_PASS flags are specified,
removefile
()
will proceed using the flag that specifies the highest number of overwriting
passes.
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.
removefile
()
operates on symbolic links, rather than the target of the link.
/* 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); /* 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);
The removefile
() API was introduced in Mac
OS X 10.5.
March 16, 2023 | macOS 14.6 |