<!--
{
  "availability" : [
    "iOS: 2.0.0 -",
    "iPadOS: 2.0.0 -",
    "macCatalyst: 13.0.0 -",
    "macOS: 10.0.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/NSString/write(to:atomically:encoding:)",
  "metadataVersion" : "0.1.0",
  "role" : "Instance Method",
  "symbol" : {
    "kind" : "Instance Method",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "c:objc(cs)NSString(im)writeToURL:atomically:encoding:error:"
  },
  "title" : "write(to:atomically:encoding:)"
}
-->

# write(to:atomically:encoding:)

Writes the contents of the receiver to the URL specified by `url` using the specified encoding.

```
func write(to url: URL, atomically useAuxiliaryFile: Bool, encoding enc: UInt) throws
```

## Parameters

`url`

The URL to which to write the receiver. Only file URLs are supported.

`useAuxiliaryFile`

If <doc://com.apple.documentation/documentation/Swift/true>, the receiver is written to an auxiliary file, and then the auxiliary file is renamed to `url`. If <doc://com.apple.documentation/documentation/Swift/false>, the receiver is written directly to `url`. The <doc://com.apple.documentation/documentation/Swift/true> option guarantees that `url`, if it exists at all, won’t be corrupted even if the system should crash during writing.

    The     `useAuxiliaryFile`     parameter is ignored if     `url`     is not of a type that can be accessed atomically.

`enc`

The encoding to use for the output.

## Discussion

This method stores the specified encoding with the file in an extended attribute under the name `com.apple.TextEncoding`. The value contains the IANA name for the encoding and the <doc://com.apple.documentation/documentation/CoreFoundation/CFStringEncoding> value for the encoding, separated by a semicolon. The `CFStringEncoding` value is written as an ASCII string containing an unsigned 32-bit decimal integer and is not terminated by a null character. One or both of these values may be missing. Examples of the value written include the following:

- `MACINTOSH;0`
- UTF-8;134217984
- `UTF-8;`
- `;3071`

The methods [`init(contentsOfFile:usedEncoding:)`](/documentation/Foundation/NSString/init(contentsOfFile:usedEncoding:)), `NSString/init(contentsOfURL:usedEncoding:)-2c72d`, [`stringWithContentsOfFile:usedEncoding:error:`](/documentation/Foundation/NSString/stringWithContentsOfFile:usedEncoding:error:), and `NSString/init(contentsOfURL:usedEncoding:)-9jrum` use this information to open the file using the right encoding.

> Note:
> In the future this attribute may be extended compatibly by adding additional information after what’s there now, so any readers should be prepared for an arbitrarily long value for this attribute, with stuff following the `CFStringEncoding` value, separated by a non-digit.

> Handling Errors in Swift:
> In Swift, this method returns `Void` and is marked with the `throws` keyword to indicate that it throws an error in cases of failure.
> 
> You call this method in a `try` expression and handle any errors in the `catch` clauses of a `do` statement, as described in [Error Handling](https://docs.swift.org/swift-book/LanguageGuide/ErrorHandling.html) in [The Swift Programming Language](https://docs.swift.org/swift-book/) and `About Imported Cocoa Error Parameters`.

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)