GNU Info

(elisp)Writing to Files

---

Next: File Locks Prev: Reading from Files Up: Files

---

Enter node , (file) or (file)node

Writing to Files
================

   You can write the contents of a buffer, or part of a buffer, directly
to a file on disk using the `append-to-file' and `write-region'
functions.  Don't use these functions to write to files that are being
visited; that could cause confusion in the mechanisms for visiting.

 - Command: append-to-file start end filename
     This function appends the contents of the region delimited by
     START and END in the current buffer to the end of file FILENAME.
     If that file does not exist, it is created.  This function returns
     `nil'.

     An error is signaled if FILENAME specifies a nonwritable file, or
     a nonexistent file in a directory where files cannot be created.

 - Command: write-region start end filename &optional append visit
          lockname mustbenew
     This function writes the region delimited by START and END in the
     current buffer into the file specified by FILENAME.

     If START is a string, then `write-region' writes or appends that
     string, rather than text from the buffer.  END is ignored in this
     case.

     If APPEND is non-`nil', then the specified text is appended to the
     existing file contents (if any).  Starting in Emacs 21, if APPEND
     is an integer, then `write-region' seeks to that byte offset from
     the start of the file and writes the data from there.

     If MUSTBENEW is non-`nil', then `write-region' asks for
     confirmation if FILENAME names an existing file.  Starting in
     Emacs 21, if MUSTBENEW is the symbol `excl', then `write-region'
     does not ask for confirmation, but instead it signals an error
     `file-already-exists' if the file already exists.

     The test for an existing file, when MUSTBENEW is `excl', uses a
     special system feature.  At least for files on a local disk, there
     is no chance that some other program could create a file of the
     same name before Emacs does, without Emacs's noticing.

     If VISIT is `t', then Emacs establishes an association between the
     buffer and the file: the buffer is then visiting that file.  It
     also sets the last file modification time for the current buffer to
     FILENAME's modtime, and marks the buffer as not modified.  This
     feature is used by `save-buffer', but you probably should not use
     it yourself.

     If VISIT is a string, it specifies the file name to visit.  This
     way, you can write the data to one file (FILENAME) while recording
     the buffer as visiting another file (VISIT).  The argument VISIT
     is used in the echo area message and also for file locking; VISIT
     is stored in `buffer-file-name'.  This feature is used to
     implement `file-precious-flag'; don't use it yourself unless you
     really know what you're doing.

     The optional argument LOCKNAME, if non-`nil', specifies the file
     name to use for purposes of locking and unlocking, overriding
     FILENAME and VISIT for that purpose.

     The function `write-region' converts the data which it writes to
     the appropriate file formats specified by `buffer-file-format'.
     Note: Format Conversion.  It also calls the functions in the list
     `write-region-annotate-functions'; see Note: Saving Properties.

     Normally, `write-region' displays the message `Wrote FILENAME' in
     the echo area.  If VISIT is neither `t' nor `nil' nor a string,
     then this message is inhibited.  This feature is useful for
     programs that use files for internal purposes, files that the user
     does not need to know about.

 - Macro: with-temp-file file body...
     The `with-temp-file' macro evaluates the BODY forms with a
     temporary buffer as the current buffer; then, at the end, it
     writes the buffer contents into file FILE.  It kills the temporary
     buffer when finished, restoring the buffer that was current before
     the `with-temp-file' form.  Then it returns the value of the last
     form in BODY.

     The current buffer is restored even in case of an abnormal exit via
     `throw' or error (Note: Nonlocal Exits).

     See also `with-temp-buffer' in Note: Current Buffer.