--- name: "removefile" section: "3" platform: "macos" package: "removefile" version: "85.100.6" release: "macOS 26.5" platforms: ["macos"] url: "https://new.carta.tech/removefile" --- # removefile(3) remove files or directories ## NAME **removefile**, **removefileat**, **removefile\_state\_alloc**, **removefile\_state\_free**, **removefile\_state\_get**, **removefile\_state\_set** – remove files or directories ## SYNOPSIS **#include \** *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*); ## 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. 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 If the *path* location is a directory, then recursively delete the entire directory. - REMOVEFILE\_KEEP\_PARENT The file or directory at the *path* location is not deleted. If specified in conjunction with REMOVEFILE\_RECURSIVE, then all of the contents of the directory at *path* location will be deleted, but not the directory itself. - REMOVEFILE\_CROSS\_MOUNT By default, recursive traversals do not cross mount points. This option allows **removefile**() to descend into directories that have a different device number than the file from which the descent began. - REMOVEFILE\_SECURE\_7\_PASS Overwrite the file with 7 US DoD compliant passes (0xF6, 0x00, 0xFF, random, 0x00, 0xFF, random). - REMOVEFILE\_SECURE\_35\_PASS Overwrite the file using 35-pass Gutmann algorithm. - REMOVEFILE\_SECURE\_3\_PASS Overwrite the file twice with random bytes, and then with 0xAA. - REMOVEFILE\_SECURE\_1\_PASS Overwrite with a single pass of random data. - REMOVEFILE\_SECURE\_1\_PASS\_ZERO Overwrite with a single pass of zeroes. - REMOVEFILE\_ALLOW\_LONG\_PATHS Allow paths traversed internally to exceed the PATH\_MAX constant. This requires changing the working directory of the process that has called into **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 Get or set the callback function of type *removefile\_callback\_t* to be called prior to file deletion. - REMOVEFILE\_STATE\_CONFIRM\_CONTEXT Get or set any parameters of type *void* *\** that are needed for the confirm callback function. - REMOVEFILE\_STATE\_ERROR\_CALLBACK Get or set the callback function of type *removefile\_callback\_t* to be called when an error is detected. - REMOVEFILE\_STATE\_ERROR\_CONTEXT Get or set any parameters of type *void* *\** that are needed for the error callback function. - REMOVEFILE\_STATE\_ERRNO Get or set the current errno of type *int* - REMOVEFILE\_STATE\_STATUS\_CALLBACK Get or set the callback function of type *removefile\_callback\_t* to be called subsequent to file deletion. - REMOVEFILE\_STATE\_STATUS\_CONTEXT Get or set any parameters of type *void* *\** that are needed for the status callback function. - REMOVEFILE\_STATE\_FTSENT Get any available file entry information of type *FTSENT* *\** (setting is not allowed). 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 File is deleted and **removefile**() continues operation as normal. - REMOVEFILE\_SKIP Current file is not deleted and **removefile**() continues operation as normal. - REMOVEFILE\_STOP Current file is not deleted and **removefile**() exits without continuing further. The **removefile\_cancel**() function is used to cancel a remove that is in progress. ## RETURN VALUES The family of **removefile**() functions returns less than 0 on error, and 0 on success. ## ERRORS **removefile**() will fail if: - \[EACCES\] The *path* location specifies a file or directory for which the calling process does not have proper permissions. - \[EINVAL\] A callback returned an invalid return value (not REMOVEFILE\_PROCEED, REMOVEFILE\_SKIP, or REMOVEFILE\_STOP) - \[EMLINK\] The *path* location refers to a symbolic link. - \[ENAMETOOLONG\] A component of the *path* location exceeds NAME\_MAX characters, or the entire *path* location exceeds PATH\_MAX characters (and REMOVEFILE\_ALLOW\_LONG\_PATHS is not passed). - \[ENOMEM\] A memory allocation failed. - \[ENOTEMPTY\] The *path* location specifies a directory that contains an immutable file which cannot be deleted. - \[EPERM\] The *path* location specifies an immutable file that cannot be deleted. **removefileat**() will fail if: - \[ENOTDIR\] The *path* argument is not an absolute path and *fd* is neither AT\_FDCWD nor a file descriptor associated with a directory. **removefile\_cancel**() will fail if: - \[EINVAL\] A *NULL* parameter was passed into **removefile\_cancel**(). In addition, all functions may return an error from an underlying library or system call. ## NOTES 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. REMOVEFILE\_ALLOW\_LONG\_PATHS may change the working directory of the process, making it not thread safe. ## EXAMPLE ``` /* 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); ``` ## SEE ALSO [unlink(1)](/unlink/1.md), [sync(2)](/sync/2.md), [sync\_volume\_np(3)](/sync_volume_np/3.md) ## HISTORY The **removefile**() API was introduced in Mac OS X 10.5.