REMOVEFILE(3) BSD Library Functions Manual REMOVEFILE(3)

NAME
     rreemmoovveeffiillee, rreemmoovveeffiilleessttaatteeaalllloocc, rreemmoovveeffiilleessttaatteeffrreeee,
     rreemmoovveeffiilleessttaatteeggeett, rreemmoovveeffiilleessttaatteesseett - remove files or directories

SYNOPSIS
     ##iinncclluuddee <>

     int
     rreemmoovveeffiillee(const char *path, removefilestatet state,
         removefileflagst flags);

     removefilestatet
     rreemmoovveeffiilleessttaatteeaalllloocc(void);

     int
     rreemmoovveeffiilleessttaatteeffrreeee(removefilestatet state);

     int
     rreemmoovveeffiilleessttaatteeggeett(removefilestatet state, uint32t key, void * dst);

     int
     rreemmoovveeffiilleessttaatteesseett(removefilestatet state, uint32t key,
         const void * value);

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 rreemmoovveeffiilleessttaatteeaalllloocc() function initializes a removefilestatet
     object (which is an opaque data type).  This object can be passed to
     rreemmoovveeffiillee().  rreemmoovveeffiilleessttaatteeggeett() and rreemmoovveeffiilleessttaatteesseett() can be
     used to manipulate the state (see below).  The rreemmoovveeffiilleessttaatteeffrreeee()
     function is used to deallocate the object and its contents.

     The rreemmoovveeffiillee() 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
     rreemmoovveeffiilleessttaatteeaalllloocc(), then rreemmoovveeffiillee() will use the information from
     the state object; if it is NULL, then rreemmoovveeffiillee() will work normally,
     but less control will be available to the caller.  The flags parameter
     controls deletion options:

     REMOVEFILERECURSIVE       If the path location is a directory, then
                                recursively delete the entire directory.

     REMOVEFILEKEEPPARENT     The file or directory at the path location is
                                not deleted.  If specified in conjunction with
                                REMOVEFILERECURSIVE, then all of the contents
                                of the directory at path location will be
                                deleted, but not the directory itself.

     REMOVEFILESECURE7PASS   Overwrite the file with 7 US DoD compliant
                                passes (0xF6, 0x00,  0xFF,  random, 0x00,
                                0xFF, random)

     REMOVEFILESECURE35PASS  Overwrite the file using 35-pass Gutmann algo-
                                rithm.

     REMOVEFILESECURE1PASS   Overwrite with a single pass of random data

     The rreemmoovveeffiilleessttaatteeggeett() and rreemmoovveeffiilleessttaatteesseett() functions can be
     used to manipulate the removefilestatet object returned by
     rreemmoovveeffiilleessttaatteeaalllloocc().  In both functions, the dst or the value param-
     eter's type depends on the key parameter that is passed in.

     REMOVEFILESTATECONFIRMCALLBACK  Get or set the callback function of
                                        type removefilecallbackt to be
                                        called prior to file deletion.

     REMOVEFILESTATECONFIRMCONTEXT   Get or set any parameters of type void
                                        * that are needed for the confirm
                                        callback function.

     REMOVEFILESTATEERRORCALLBACK    Get or set the callback function of
                                        type removefilecallbackt to be
                                        called when an error is detected.

     REMOVEFILESTATEERRORCONTEXT     Get or set any parameters of type void
                                        * that are needed for the error call-
                                        back function.

     REMOVEFILESTATEERRNO             Get or set the current errno of type
                                        int

     REMOVEFILESTATESTATUSCALLBACK   Get or set the callback function of
                                        type removefilecallbackt to be
                                        called subsequent to file deletion.

     REMOVEFILESTATESTATUSCONTEXT    Get or set any parameters of type void
                                        * that are needed for the status call-
                                        back function.

     The removefilecallbackt function pointer is defined as the following:

     int (*removefilecallbackt) (removefilestatet state, const char *path,
     void *context)

     The return value of the callback function is given as:

     REMOVEFILEPROCEED  File is deleted and rreemmoovveeffiillee() continues operation
                         as normal.

     REMOVEFILESKIP     Current file is not deleted and rreemmoovveeffiillee() contin-
                         ues operation as normal.

     REMOVEFILESTOP     Current file is not deleted and rreemmoovveeffiillee() exits
                         without continuing further.

RETURN VALUES
     The family of rreemmoovveeffiillee() functions returns less than 0 on error, and 0
     on success.

EERRRROORRSS
     rreemmoovveeffiillee() will fail if:

     [EACCES]           The path location specifies a file or directory for
                        which the calling process does not have proper permis-
                        sions.

     [EINVAL]           A callback returned an invalid return value (not
                        REMOVEFILEPROCEED, REMOVEFILESKIP, or REMOVE-
                        FILESTOP)

     [EMLINK]           The path location refers to a symbolic link.

     [ENAMETOOLONG]     The resource fork name of the file exceeds the maximum
                        allowed length.

     [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.

     In addition, both functions may return an error from an underlying
     library or system call.

NNOOTTEESS
     Write protected files owned by another process cannot be removed by
     rreemmoovveeffiillee(), regardless of the permissions on the directory containing
     the file.

     If multiple of the REMOVEFILESECURE1PASS, REMOVEFILESECURE7PASS,
     and REMOVEFILESECURE35PASS flags are specified, rreemmoovveeffiillee() will pro-
     ceed using the flag that specifies the highest number of overwriting
     passes.

EEXXAAMMPPLLEESS
           /* Initialize a state variable */
           removefilestatet s;
           s = removefilestatealloc();
           /* Recursively remove all files and directories while keeping parent tmp directory. */
           removefile("/tmp", s, REMOVEFILERECURSIVE | REMOVEFILEKEEPPARENT);
           /* Release the state variable */
           removefilestatefree(s);

           /* A more complex way to call removefile() - define a callback function */
           int removefilestatuscallback(removefilestatet state, const char * path, void * context) {
              fprintf(stderr, "File deleted: %s", path);
              return REMOVEFILEPROCEED;
           }
           /* Initialize a state variable */
           s = removefilestatealloc();
           /* Set callback function properties */
           removefilestateset(s, REMOVEFILESTATECONFIRMCALLBACK, removefileconfirmcallback);
           removefilestateset(s, REMOVEFILESTATECONFIRMCONTEXT, NULL);
           /* Recursively remove all files and directories while keeping parent tmp directory,
              calling a confirm callback prior to each file deletion. */
           removefile("/tmp", s, REMOVEFILERECURSIVE | REMOVEFILEKEEPPARENT);
           /* Release the state variable. */
           removefilestatefree(s);

SEE ALSO
     srm(1), unlink(1)

HISTORY     The rreemmoovveeffiillee() API was introduced in Mac OS X 10.5.

BSD                               May 4, 2007                              BSD