mkdirat()

Updated: April 19, 2023

Create a directory at a given location

Synopsis:

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

int mkdirat( int fd, 
             const char* path,
             mode_t mode );

Arguments:

fd
A file descriptor that indicates the base directory for relative file paths. The pathname given in path is resolved by appending it to the directory associated with fd. You can set this argument to AT_FDCWD to use the current working directory as the base directory.
Note: You must use a file descriptor obtained from an open() call with the O_DIRECTORY flag set. Otherwise, the function fails and sets errno to ENOTDIR.

If path specifies an absolute path, fd has no effect.

path
The pathname of the directory you want to create. This path can be absolute or relative; for details of how relative path resolution is done, see above.
mode
The permissions for the directory, modified by the process's file-creation mask (see umask()).

The access permissions for the directory are specified as a combination of bits defined in <sys/stat.h>. For more information, see the entry for struct stat.

Library:

libc

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

Description:

The mkdirat() function creates a new directory named path. The path argument can contain an absolute or relative path. In the latter case, the fd argument is used to resolve the pathname, as explained in this argument's description (above).

If the access mode of the open file description associated with the fd file descriptor is not O_SEARCH, the function checks if directory searches are permitted using the current permissions of the directory underlying the file descriptor. If the access mode is O_SEARCH, the function doesn't perform the check.

QNX Neutrino has no concept of a path operation (open(), readlink(), etc.) that references a path relative to an already open file descriptor (for a directory), as far as the filesystem resource manager is concerned. Therefore, it's not possible to eliminate the race inherent in looking up a pathname with multiple intervening directories or symbolic links. However, mkdirat() can still be used for maintaining a per-thread current working directory, using file descriptors maintained by the application.

Note: Not all filesystems support the creation of directories. For example, /dev/shmem (which really isn't a filesystem but looks like one) doesn't. For more information, see the Working with Filesystems chapter of the QNX Neutrino User's Guide.

The newly created directory is empty.

The directory's owner ID is set to the process's effective user ID. The directory's group ID is set to the group ID of the parent directory (if the parent set-group ID bit is set) or to the process's effective group ID.

The file permission bits of the new directory are initialized from mode. For information about how these bits and other affected bits behave, and about which fields of the new directory and its parent directory are updated, see the mkdir() reference.

Returns:

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

Errors:

EACCES
Search permission is denied on a component of the path prefix of path, write permission is denied on the parent directory of path, or the access mode of the fd file descriptor is not O_SEARCH and the underlying directory doesn't permit directory searches.
EBADF
The path argument does not specify an absolute path and the fd argument is neither AT_FDCWD nor a valid file descriptor open for reading or searching.
EEXIST
The directory named by path already exists.
ELOOP
During resolution of the path argument, a loop was found in the symbolic links or more than SYMLOOP_MAX symbolic links were encountered.
EMLINK
The link count of the parent directory would exceed LINK_MAX.
ENAMETOOLONG
The length of the path string exceeds PATH_MAX, the resolution of a symbolic link within path produced a result longer than PATH_MAX, or a pathname component is longer than NAME_MAX.
ENOENT
A pathname component in the specified path doesn't exist, or path is an empty string.
ENOSPC
The filesystem doesn't contain enough space to hold the contents of the new directory or to extend the parent directory.
ENOSYS
This function isn't supported for this path.
ENOTDIR
A component of the path prefix names an existing file that is neither a directory nor a symbolic link to one, or the path argument isn't an absolute path and fd is associated with a non-directory file. Or, the file descriptor in fd was created without O_DIRECTORY set.
EROFS
The parent directory resides on a read-only filesystem.

Classification:

POSIX 2008

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