# fsys.atomicFile 库模块帮助文档

[原子文件替换](https://www.aardio.com/zh-cn/docs/library/fsys/atomicFile/index.html)

## fsys.atomicFile 成员列表 <a id="fsys.atomicFile" href="#fsys.atomicFile">&#x23;</a>

本地固定磁盘 NTFS 的单文件原子命名替换。  
不是多文件事务或掉电耐久保证；不保留旧目标 ACL/时间戳/备用流，不自动创建父目录。

### fsys.atomicFile.prepare() <a id="fsys.atomicFile.prepare" href="#fsys.atomicFile.prepare">&#x23;</a>
[返回对象:atomicPreparedObject](#atomicPreparedObject)

### fsys.atomicFile.prepare(目标路径,字符串或buffer,选项表) <a id="fsys.atomicFile.prepare" href="#fsys.atomicFile.prepare">&#x23;</a>
在目标同目录独占创建临时文件，完整写入，默认 FlushFileBuffers。  
成功返回 prepared 对象；失败返回 null,错误信息,结果表。结果含 cleanupError/pending 时必须处理清理失败。

### fsys.atomicFile.write() <a id="fsys.atomicFile.write" href="#fsys.atomicFile.write">&#x23;</a>
[返回对象:atomicFileResultObject](#atomicFileResultObject)

### fsys.atomicFile.write(目标路径,字符串或buffer,选项表) <a id="fsys.atomicFile.write" href="#fsys.atomicFile.write">&#x23;</a>
准备并提交；失败自动清理未提交临时文件。始终返回结果表，不要直接把结果当布尔值。  
选项仅 flush=true、replaceExisting=true；false 可禁用刷新或只创建不覆盖。无自动重试。

## atomicFileResultObject 成员列表 <a id="atomicFileResultObject" href="#atomicFileResultObject">&#x23;</a>

### atomicFileResultObject.bytesWritten <a id="atomicFileResultObject.bytesWritten" href="#atomicFileResultObject.bytesWritten">&#x23;</a>
成功写入调用所报告的字节总数。

### atomicFileResultObject.cleanupError <a id="atomicFileResultObject.cleanupError" href="#atomicFileResultObject.cleanupError">&#x23;</a>
独立清理错误 {code;message;systemCode}，不意味着提交被撤销。

### atomicFileResultObject.code <a id="atomicFileResultObject.code" href="#atomicFileResultObject.code">&#x23;</a>
主错误代码；error 为描述，systemCode 为可选 Win32 错误代码。

### atomicFileResultObject.committed <a id="atomicFileResultObject.committed" href="#atomicFileResultObject.committed">&#x23;</a>
是否已完成原子重命名；一旦 true 不会因后续清理失败变回 false。

### atomicFileResultObject.error <a id="atomicFileResultObject.error" href="#atomicFileResultObject.error">&#x23;</a>
主错误描述；准备失败或提交失败不会被后续 cleanupError 掩盖。

### atomicFileResultObject.flushed <a id="atomicFileResultObject.flushed" href="#atomicFileResultObject.flushed">&#x23;</a>
是否成功请求过提交前 FlushFileBuffers；不是断电耐久保证。

### atomicFileResultObject.handleOpen <a id="atomicFileResultObject.handleOpen" href="#atomicFileResultObject.handleOpen">&#x23;</a>
本对象是否仍持有句柄。

### atomicFileResultObject.ok <a id="atomicFileResultObject.ok" href="#atomicFileResultObject.ok">&#x23;</a>
本次请求及必要清理是否全部完成；请同时检查 committed。

### atomicFileResultObject.pending <a id="atomicFileResultObject.pending" href="#atomicFileResultObject.pending">&#x23;</a>
write/prepare 失败时仍持句柄的对象；保留并调用 close 重试清理，不要盲目重写目标。

### atomicFileResultObject.pending. <a id="atomicFileResultObject.pending." href="#atomicFileResultObject.pending.">&#x23;</a>
[返回对象:atomicPreparedObject](#atomicPreparedObject)

### atomicFileResultObject.state <a id="atomicFileResultObject.state" href="#atomicFileResultObject.state">&#x23;</a>
new / prepared / aborting / aborted / committed。

### atomicFileResultObject.targetPath <a id="atomicFileResultObject.targetPath" href="#atomicFileResultObject.targetPath">&#x23;</a>
规范化目标绝对路径。

### atomicFileResultObject.tempPath <a id="atomicFileResultObject.tempPath" href="#atomicFileResultObject.tempPath">&#x23;</a>
临时文件原绝对路径，提交后仅供诊断，不能据此删除文件。

### atomicFileResultObject.tempState <a id="atomicFileResultObject.tempState" href="#atomicFileResultObject.tempState">&#x23;</a>
absent / owned / delete-pending，表示本对象的临时文件状态。  
close 成功后也可能 delete-pending：外部元数据句柄令系统延迟删除。再次 close 仅复核，不按路径删除。

## atomicPreparedObject 成员列表 <a id="atomicPreparedObject" href="#atomicPreparedObject">&#x23;</a>

### atomicPreparedObject.close() <a id="atomicPreparedObject.close" href="#atomicPreparedObject.close">&#x23;</a>
未提交：按原句柄标记删除并关闭；已提交：仅关闭句柄，不删除目标。  
返回结果表；失败保留句柄供重试。可重复调用；GC 仅尽力兜底。

[返回对象:atomicFileResultObject](#atomicFileResultObject)

### atomicPreparedObject.commit() <a id="atomicPreparedObject.commit" href="#atomicPreparedObject.commit">&#x23;</a>
返回结果表。失败保留 prepared，可显式重试或 close。  
committed=true 后绝不再次替换或回滚；ok=false 且 committed=true 仅表示后续清理失败。

[返回对象:atomicFileResultObject](#atomicFileResultObject)

### atomicPreparedObject.status() <a id="atomicPreparedObject.status" href="#atomicPreparedObject.status">&#x23;</a>
返回状态快照；不探查后来外部写入。对象仅在创建线程内使用，不可序列化传递。

[返回对象:atomicFileResultObject](#atomicFileResultObject)