rmdir()

Delete an empty directory

Synopsis:

#include <sys/types.h>
#include <unistd.h>

int rmdir( const char* path );

Arguments:

path
The path of the directory that you want to delete. This path can be relative to the current working directory, or an absolute path.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The rmdir() function removes (deletes) the specified directory. The directory must not contain any files or directories.


Note: If the directory is the current working directory of any process, rmdir() returns -1 and sets errno to EINVAL. If the directory is the root directory, the effect of this function depends on the filesystem.

The space occupied by the directory is freed, making it inaccessible, if its link count becomes zero and no process has the directory open (opendir()). If a process has the directory open when the last link is removed, the . and .. entries are removed and no new entries can be created in the directory. In this case, the directory will be removed when all references to it have been closed (closedir()).

When successful, rmdir() marks st_ctime and st_mtime for update in the parent directory.

Returns:

0
Success.
-1
An error occurred (errno is set).

Errors:

EACCES
Search permission is denied for a component of path, or write permission is denied on the parent directory of the directory to be removed.
EBUSY
The directory named by path can't be removed because it's being used by another process, and the implementation considers this to be an error.
EEXIST
The path argument names a directory that isn't empty.
ELOOP
Too many levels of symbolic links.
ENAMETOOLONG
The argument path exceeds PATH_MAX in length, or a pathname component is longer than NAME_MAX.
ENOENT
The specified path doesn't exist, or path is an empty string.
ENOSYS
The rmdir() function isn't implemented for the filesystem specified in path.
ENOTDIR
A component of path isn't a directory.
ENOTEMPTY
The path argument names a directory that isn't empty.
EROFS
The directory entry to be removed resides on a read-only filesystem.

Examples:

To remove the directory called /home/terry:

#include <stdlib.h>
#include <sys/types.h>
#include <sys/stat.h>

int main( void )
{
    (void)rmdir( "/home/terry" );
    
    return EXIT_SUCCESS;
}

Classification:

POSIX 1003.1

Safety:
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes

See also:

chdir(), chmod(), errno, fchdir(), getcwd(), mkdir(), stat()