RunMat
GitHub

View all functions

CategoryIo: Repl Fs

What does the mkdir function do in MATLAB / RunMat?

mkdir creates new folders on disk. It mirrors MATLAB by accepting either a single path string or a parent-folder plus child-name pair, and it returns diagnostic status information instead of throwing errors for most filesystem failures.

How does the mkdir function behave in MATLAB / RunMat?

  • status = mkdir(folder) creates folder, returning 1 when the directory is created or already exists, and 0 on failure. Status outputs are double scalars for MATLAB compatibility.
  • [status, message, messageID] = mkdir(parent, child) creates the directory fullfile(parent, child). When the directory is created during this call, the message outputs are empty. If the directory already exists, MATLAB populates them with 'Directory already exists.' and 'MATLAB:MKDIR:DirectoryExists'. Failures return the system error text and message identifier.
  • The optional message and messageID outputs are character arrays (with size 1×0 when empty), matching MATLAB’s behaviour. Callers that prefer string scalars can wrap them with string(message).
  • Passing a parent folder that does not exist leaves the filesystem unchanged and returns status = 0.
  • If the target path already exists as a file, mkdir fails gracefully with status = 0 and a diagnostic message; it does not overwrite files.
  • Path arguments accept character vectors or string scalars. Other input types raise mkdir: folder name must be a character vector or string scalar (or the equivalent message for the parent argument).
  • The builtin expands ~ to the user’s home directory and honours relative paths with respect to the current working folder (pwd).

mkdir Function GPU Execution Behaviour

mkdir performs host-side filesystem operations. When callers supply GPU-resident scalars (for example, gpuArray("logs")), RunMat gathers the value back to the CPU before resolving the path. Acceleration providers do not publish hooks for this builtin, so there is no device-side implementation to enable.

GPU residency in RunMat (Do I need gpuArray?)

No. mkdir executes entirely on the host—GPU residency provides no benefit. However, if a script accidentally stores path strings on the GPU, RunMat automatically gathers them before accessing the filesystem so the call still succeeds.

Examples of using the mkdir function in MATLAB / RunMat

Create A New Folder In The Current Directory

status = mkdir("results");

Expected output:

status =
     1

Create A Nested Folder Using Parent And Child Arguments

status = mkdir("data", "archive/2024");

Expected output:

status =
     1

Detect When A Folder Already Exists

mkdir("logs");
[status, message, messageID] = mkdir("logs");

Expected output:

status =
     1

message =
Directory already exists.

messageID =
MATLAB:MKDIR:DirectoryExists

Handle Missing Parent Folder Gracefully

[status, message, messageID] = mkdir("missing-parent", "child");

Expected output:

status =
     0
message =
Parent folder "missing-parent" does not exist.
messageID =
MATLAB:MKDIR:ParentDirectoryDoesNotExist

Capture Detailed Status And Messages

[status, message, messageID] = mkdir("reports");

Expected output:

status =
     1
message =

messageID =

Create A Folder In Your Home Directory With Tilde Expansion

status = mkdir("~", "RunMatProjects");

Expected output:

status =
     1

Use gpuArray Inputs For Paths

status = mkdir(gpuArray("gpu-output"));

Expected output:

status =
     1

FAQ

  • What status codes does mkdir return? 1 indicates success (the directory exists afterwards), and 0 indicates failure. Status values are doubles to match MATLAB.
  • Does mkdir overwrite existing files? No. If the target path already exists as a regular file, mkdir returns status = 0 and reports that the path is not a directory.
  • Can I create multiple levels of folders at once? Yes when you provide a single path, because RunMat mirrors MATLAB’s behaviour of creating intermediate directories. When using the two-argument form, the parent folder must already exist.
  • Does mkdir support string scalars and character vectors? Yes. String arrays must contain exactly one element; other types raise an error.
  • How are error messages returned? Failures return descriptive messages and MATLAB-style message IDs (for example, MATLAB:MKDIR:OSError) in the second and third outputs. The builtin does not throw unless the inputs are invalid.
  • Are UNC paths and drive-letter paths supported on Windows? Yes. Provide the path exactly as you would in MATLAB; RunMat forwards it to the operating system.
  • Can I run mkdir on the GPU? No. The function operates on the host, but it automatically gathers GPU-resident inputs for convenience.
  • What happens if the folder already exists? mkdir reports success (status = 1) and leaves the directory untouched, just like MATLAB.
  • Does tilde (~) expand to the home directory? Yes. Both single-argument and two-argument forms expand ~ at the start of a path.
  • How do I handle errors programmatically? Capture the optional outputs and test status. When it is 0, inspect message and messageID for diagnostics.

See Also

cd, pwd, ls, dir

Source & Feedback