Info Catalog elisp: Reading from Files elisp: Files elisp: File Locks

elisp: Writing to Files

 
 24.4 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.
 
      When called from Lisp, this function is completely equivalent to:
 
           (write-region start end filename t)
 
  -- 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 ‘nil’, then the command writes the entire buffer
      contents (_not_ just the accessible portion) to the file and
      ignores END.
 
      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).  If APPEND is a number,
      ‘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.  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’ and
      also calls the functions in the list
      ‘write-region-annotate-functions’.  Format Conversion.
 
      Normally, ‘write-region’ displays the message ‘Wrote FILENAME’ in
      the echo area.  This message is inhibited if VISIT is neither ‘t’
      nor ‘nil’ nor a string, or if Emacs is operating in batch mode
      (Batch Mode).  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 (Nonlocal Exits).
 
      See also ‘with-temp-buffer’ in The Current Buffer Definition
      of with-temp-buffer.
 

Info Catalog elisp: Reading from Files elisp: Files elisp: File Locks