DtEditorSaveContentsToFile(3)

     NAME
          DtEditorSaveContentsToFile - save the contents of a DtEditor
          widget to a file

     SYNOPSIS
          #include <Dt/Editor.h>

          DtEditorErrorCode DtEditorSaveContentsToFile(Widget widget,
                                                       char *fileName,
                                                       Boolean overwriteIfExists,
                                                       Boolean hardCarriageReturns,
                                                       Boolean markContentsAsSaved);

     DESCRIPTION
          The DtEditorSaveContentsToFile() function saves the entire
          contents of the DtEditor widget to a file, optionally
          replacing soft line feeds (word wraps) with <newline>s.  If
          the file does not exist and the directory has the correct
          write permissions, the file is created.  If the file exists
          and the overwriteIfExists argument is set to True, the
          contents of the file are overwritten.  If the file or its
          directory does not have the correct write permissions, an
          error is returned.

          The DtEditor widget tracks whether its contents have changed
          since they were last saved or retrieved.  If the
          markContentsAsSaved argument is set to False, a copy of the
          data is saved without affecting whether
          DtEditorCheckForUnsavedChanges(3) reports that there are
          unsaved changes.  This is useful if the application needs to
          save a copy of the contents to a temporary file.

          The widget argument specifies the DtEditor widget ID.

          The fileName argument is the pathname of the file relative
          to the local system.

          The overwriteIfExists argument, if set to True, causes
          DtEditorSaveContentsToFile() to save the widget contents
          even though the file specified by the fileName argument
          exists and has correct write permissions.  If this argument
          is set to False, DtEditorSaveContentsToFile() returns
          DtEDITOR_WRITABLE_FILE.

          The hardCarriageReturns argument, if set to True, indicates
          that the widget should replace any soft line feeds (word
          wraps) with <newline>s when saving the data.  When this
          argument is set to False, any line wrapped because it
          reaches the right edge of the window, is saved as one
          complete line.

          The markContentsAsSaved argument, when set to True, causes
          the DtEditor widget to mark that all changes made to date
          have been saved.  When this argument is set to False, the
          DtEditor widget does not change its status regarding unsaved
          changes.  If an error arises during the save, the status
          does not change, regardless of the value of the
          markContentsAsSaved argument.

          For a complete definition of the DtEditor widget and its
          associated resources, see DtEditor(3).

     RETURN VALUE
          Upon successful completion, the DtEditorSaveContentsToFile()
          function returns DtEDITOR_NO_ERRORS; otherwise, if it cannot
          save the data to the file, the function returns one of the
          following values:

             DtEDITOR_INVALID_FILENAME
                   No file was specified.

             DtEDITOR_UNWRITABLE_FILE
                   The application does not have write permission for
                   the file or directory.

             DtEDITOR_CHAR_SPECIAL_FILE
                   The file is a device-special file.

             DtEDITOR_BLOCK_MODE_FILE
                   The file is a block-mode device.

             DtEDITOR_NO_FILE_ACCESS
                   The file cannot be accessed.

             DtEDITOR_SAVE_FAILED
                   The contents could not be saved for an unspecified
                   reason.

             DtEDITOR_WRITABLE_FILE
                   The named files exist and the overwriteIfExists
                   argument is set to False.

     EXAMPLES
          The following code segment saves the contents of a DtEditor
          widget to the local file, Foo, substituting <newline>s for
          soft line feeds.  It also indicates that all changes to the
          contents of the widget have been saved.

               Widget                  editor;
               DtEditorErrorCode       status;
               char                    *fname = "Foo";
               Boolean                 overwrite = False,
                                       hardReturns = True,
                                       markContentsAsSaved = True;

               status = DtEditorSaveContentsToFile(editor, fname, overwrite,
                                                   hardReturns, markContentsAsSaved);

               switch(status )
               {
                       case DtEDITOR_NO_ERRORS:
                               break;
                       case DtEDITOR_WRITABLE_FILE:
                               printf("Save failed.  The file already exists.\n");
                               break;

                       default:
                               printf("Could not save contents.\n");
                               break;
               }

     APPLICATION USAGE
          The application should use DtEditorGetContents(3) to
          retrieve the data in a memory buffer, rather than a disk
          file.

     SEE ALSO
          DtEditor(5), DtEditor(3), DtEditorAppend(3),
          DtEditorAppendFromFile(3),
          DtEditorCheckForUnsavedChanges(3), DtEditorGetContents(3),
          DtEditorInsert(3), DtEditorInsertFromFile(3),
          DtEditorReplace(3), DtEditorReplaceFromFile(3),
          DtEditorSetContentsFromFile(3), DtEditorSetContents(3).