What does `nil` as second argument do in `write-file` command?

Question

In a previous question I asked how to add a "Save as" button to the toolbar:

Add Save as button to org mode toolbar

and got a great answer:

(tool-bar-add-item-from-menu 'write-file "save" nil :label "Save As")

I then asked "What does the nil do?" and got a very extensive answer as to how the nil works, ie a very complex explanation of how all the code works.

I do appreciate the time that the person took to explain this very extensive answer, but this totally overloaded me, since I do not understand emacs programming.

For this reason, I have never added a Save as button to the toolbar, because I dont know what the nil does.

But it would save me a great deal of time if I had a Save as button.

I maybe did not ask properly last time, I did not explain what I was looking for.

So I would like to ask again, and I will try to rephrase my question:

What does the nil as second argument do? Not knowing what it does, I am concerned eg does it save the file in a different format? Or does bypass some part of the saving-file routine?

I am concerned this nil negatively affects how a file is saved. I just want to feel confident that if I use the above Save as command, that it does not have a risk of eg file corruption. Or of course, maybe nil does not in any way change how a file is saved.

I guess for me it just boils down to "Is using nil as the second argument safe?"

I use emacs all the time for very important files, and don't feel comfortable adding a Save as button if I don't know fully what the command does.

Please note that to me, "what" nil does is very different to "how it works" which is what was explained to me last time, and completely overloaded me, I could not understand this previous answer at all.

I am just asking for a brief answer like eg:

Yes using the nil is safe (or not), and (eg) nil is just a dummy parameter in the command to satisfy the requirement for parameter in this command, and does not change how the file is saved at all.

But not what I made up above :) but instead the real answer :)

Answer 1

It's as safe as invoking the function without that arg. Not supplying a nil optional arg is the same thing as supplying a nil arg.

C-h f write-file says:

write-file is an interactive compiled Lisp function in files.el.

It is bound to C-x C-w, menu-bar file write-file.

(write-file FILENAME &optional CONFIRM)

Write current buffer into file FILENAME.

This makes the buffer visit that file, and marks it as not modified.

Interactively, prompt for FILENAME. If you specify just a directory name as FILENAME, that means to write to a file in that directory. In this case, the base name of the file is the same as that of the file visited in the buffer, or the buffer name sans leading directories, if any, if the buffer is not already visiting a file.

You can also yank the file name into the minibuffer to edit it, using M-n.

If optional second arg CONFIRM is non-nil, this function asks for confirmation before overwriting an existing file. Interactively, confirmation is required unless you supply a prefix argument.

You can test this yourself:

1. In the *Help* buffer from C-h f write-file, use M-: (write-file "toss-me-when-done" t).

2. That creates a file toss-me-when-done, with the *Help* buffer text.

3. Repeat step 1. You are prompted to confirm overwriting the (now) existing file toss-me-when-done. Depending on your response, the previously written file is overwritten.

Using nil instead of non-nil (e.g. t) as the second arg omits prompting the user for confirmation. So it's less "safe" than using t as the second argument. But using t (any non-nil value) prompts the user. So if you intend to do the saving without any user interaction then that's not what you want. In that case, it's up to your program to test whether the file already exists, and if so, to do whatever is the right thing (overwrite or not), according o the program's logic.