Function: org-iread-file-name

org-iread-file-name is a function alias for read-file-name, defined in minibuffer.el.gz.

This function is obsolete since 9.0; use read-file-name instead.

Signature

(org-iread-file-name PROMPT &optional DIR DEFAULT-FILENAME MUSTMATCH INITIAL PREDICATE)

Documentation

Read a file name, prompting with PROMPT and completing in directory DIR.

Return the file name as a string. The return value is not expanded---you must call expand-file-name yourself.

DIR is the directory to use for completing relative file names. It should be an absolute directory name, or nil (which means the current buffer's value of default-directory).

DEFAULT-FILENAME specifies the default file name to return if the user exits the minibuffer with the same non-empty string inserted by this function. If DEFAULT-FILENAME is a string, that serves as the default. If DEFAULT-FILENAME is a list of strings, the first string is the default. If DEFAULT-FILENAME is omitted or nil, then if INITIAL is non-nil, the default is DIR combined with INITIAL; otherwise, if the current buffer is visiting a file, that file serves as the default; otherwise, the default is simply the string inserted into the minibuffer.

If the user exits with an empty minibuffer, return an empty string. (This happens only if the user erases the pre-inserted contents, or if insert-default-directory is nil.)

Fourth arg MUSTMATCH can take the following values:
- nil means that the user can exit with any input.
- t means that the user is not allowed to exit unless
  the input is (or completes to) an existing file.
- confirm means that the user can exit with any input, but she needs
  to confirm her choice if the input is not an existing file.
- confirm-after-completion means that the user can exit with any
  input, but she needs to confirm her choice if she called
  minibuffer-complete right before minibuffer-complete-and-exit
  and the input is not an existing file.
- a function, which will be called with a single argument, the
  input unquoted by substitute-in-file-name, which see. If the
  function returns a non-nil value, the minibuffer is exited with
  that argument as the value.
- anything else behaves like t except that typing RET does not exit if
  it does non-null completion.

Fifth arg INITIAL specifies text to start with. It will be interpreted as the trailing part of DEFAULT-FILENAME, so using a full file name for INITIAL will usually lead to surprising results.

Sixth arg PREDICATE, if non-nil, should be a function of one argument; then a file name is considered an acceptable completion alternative only if PREDICATE returns non-nil with the file name as its argument.

If this command was invoked with the mouse, use a graphical file dialog if use-dialog-box is non-nil, and the window system or X toolkit in use provides a file dialog box, and DIR is not a remote file. For graphical file dialogs, any of the special values of MUSTMATCH confirm and confirm-after-completion are treated as equivalent to nil. Some graphical file dialogs respect a MUSTMATCH value of t, and some do not (or it only has a cosmetic effect, and does not actually prevent the user from entering a non-existent file).

See also read-file-name-completion-ignore-case and read-file-name-function.

Aliases

org-iread-file-name (obsolete since 9.0)