[#BloombergLP-bdls-FilesystemUtil-open-01]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdls.adoc[bdls]::xref:BloombergLP/bdls/FilesystemUtil.adoc[FilesystemUtil]::open
:relfileprefix: ../../../
:mrdocs:

Open the file at the specified `path` according to the given policies&period;

== Synopsis

Declared in `&lt;bdls&lowbar;filesystemutil&period;h&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
static
xref:BloombergLP/bdls/FilesystemUtil/FileDescriptor.adoc[FileDescriptor]
open(
    char const* path,
    xref:BloombergLP/bdls/FilesystemUtil/FileOpenPolicy.adoc[FileOpenPolicy] openPolicy,
    xref:BloombergLP/bdls/FilesystemUtil/FileIOPolicy.adoc[FileIOPolicy] ioPolicy,
    xref:BloombergLP/bdls/FilesystemUtil/FileTruncatePolicy.adoc[FileTruncatePolicy] truncatePolicy = e&lowbar;KEEP);
----

== Description

Open the file at the specified `path`, using the specified `openPolicy` to determine whether to open an existing file or create a new file, and using the specified `ioPolicy` to determine whether the file will be opened for reading, writing, or both&period; Optionally specify a `truncatePolicy` to determine whether any contents of the file will be deleted before `open` returns&period; If `truncatePolicy` is not supplied, the value `e&lowbar;KEEP` will be used&period; Return a valid `FileDescriptor` for the file on success, or `k&lowbar;INVALID&lowbar;FD` otherwise&period; If `openPolicy` is `e&lowbar;OPEN`, the file will be opened if it exists, and `open` will fail otherwise&period; If `openPolicy` is `e&lowbar;CREATE` or `e&lowbar;CREATE&lowbar;PRIVATE`, and no file exists at `path`, a new file will be created, and `open` will fail otherwise&period; If `openPolicy` is `e&lowbar;CREATE&lowbar;PRIVATE`, the file will be created with access restricted to the same userid as the caller in environments where that is supported (which does not necessarily include Windows) otherwise the system default access policy is used (e&period;g&period; &apos;0777 &amp; &#126;umask&apos;)&period; If openPolicy is e&lowbar;OPEN&lowbar;OR&lowbar;CREATE, the file will be opened if it exists, and a new file will be created otherwise&period; If `ioPolicy` is `e&lowbar;READ&lowbar;ONLY`, the returned `FileDescriptor` will allow only read operations on the file&period; If `ioPolicy` is `e&lowbar;WRITE&lowbar;ONLY` or `e&lowbar;APPEND&lowbar;ONLY`, the returned `FileDescriptor` will allow only write operations on the file&period; If `ioPolicy` is `e&lowbar;READ&lowbar;WRITE` or `e&lowbar;READ&lowbar;APPEND`, the returned `FileDescriptor` will allow both read and write operations on the file&period; Additionally, if `ioPolicy` is `e&lowbar;APPEND&lowbar;ONLY` or `e&lowbar;READ&lowbar;APPEND` all writes will be made to the end of the file (&quot;append mode&quot;)&period; If `truncatePolicy` is `e&lowbar;TRUNCATE`, the file will have zero length when `open` returns&period; If `truncatePolicy` is `e&lowbar;KEEP`, the file will be opened with its existing contents, if any&period; Note that when a file is opened in `append` mode, all writes will go to the end of the file, even if there has been seeking on the file descriptor or another process has changed the length of the file&period; Append&hyphen;mode writes are not atomic except in limited cases&semi; another thread, or even another process, operating on the file may cause output not to be written, unbroken, to the end of the file&period; (Unix environments writing to local file systems may promise more&period;) Note that `open` will fail to open a file with a `truncatePolicy` of `e&lowbar;TRUNCATE` unless at least one of the following policies is specified for `openPolicy` or `ioPolicy`&colon; &ast; `e&lowbar;CREATE` &ast; `e&lowbar;CREATE&lowbar;PRIVATE` &ast; `e&lowbar;OPEN&lowbar;OR&lowbar;CREATE` &ast; &apos;e&lowbar;WRITE&lowbar;ONLY &ast; `e&lowbar;READ&lowbar;WRITE` The parameterized `STRING&lowbar;TYPE` must be one of `bsl&colon;&colon;string`, `std&colon;&colon;string`, `std&colon;&colon;pmr&colon;&colon;string` (if supported), `bsl&colon;&colon;string&lowbar;view`, or `bslstl&colon;&colon;StringRef`&period;

== Return Value

a valid `FileDescriptor` on success, or `k&lowbar;INVALID&lowbar;FD` otherwise

== Parameters

[cols="1,4"]
|===
| Name| Description
| *path*
| filesystem path of the file to open
| *openPolicy*
| whether to open an existing file or create a new one
| *ioPolicy*
| whether the file is opened for reading, writing, or both
| *truncatePolicy*
| whether to delete existing contents on open
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#
