Macintosh-SW/syncfiles
1
0
Fork 0
mirror of https://github.com/depp/syncfiles.git synced 2024-11-22 03:30:57 +00:00
Code Issues Projects Releases Wiki Activity
gh-pages
syncfiles/tech/apis.html
Dietrich Epp 558e4f0c70 Generated from commit 2b5f5a2425
2022-04-14 12:50:38 -04:00

82 lines
29 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html> <html lang="en-US"> <head> <meta charset="UTF-8"> <meta http-equiv="X-UA-Compatible" content="IE=Edge"> <title>File APIs - SyncFiles Documentation</title> <link rel="shortcut icon" href="/syncfiles/favicon.ico" type="image/x-icon"> <link rel="stylesheet" href="/syncfiles/assets/css/just-the-docs-default.css"> <script type="text/javascript" src="/syncfiles/assets/js/vendor/lunr.min.js"></script> <script type="text/javascript" src="/syncfiles/assets/js/just-the-docs.js"></script> <meta name="viewport" content="width=device-width, initial-scale=1"> <!-- Begin Jekyll SEO tag v2.8.0 --> <title>File APIs | SyncFiles Documentation</title> <meta name="generator" content="Jekyll v4.2.2" /> <meta property="og:title" content="File APIs" /> <meta property="og:locale" content="en_US" /> <meta name="description" content="Write an awesome description for your new site here. You can edit this line in _config.yml. It will appear in your document head meta (for Google search results) and in your feed.xml site description." /> <meta property="og:description" content="Write an awesome description for your new site here. You can edit this line in _config.yml. It will appear in your document head meta (for Google search results) and in your feed.xml site description." /> <link rel="canonical" href="https://depp.github.io/syncfiles/tech/apis" /> <meta property="og:url" content="https://depp.github.io/syncfiles/tech/apis" /> <meta property="og:site_name" content="SyncFiles Documentation" /> <meta property="og:type" content="website" /> <meta name="twitter:card" content="summary" /> <meta property="twitter:title" content="File APIs" /> <script type="application/ld+json"> {"@context":"https://schema.org","@type":"WebPage","description":"Write an awesome description for your new site here. You can edit this line in _config.yml. It will appear in your document head meta (for Google search results) and in your feed.xml site description.","headline":"File APIs","url":"https://depp.github.io/syncfiles/tech/apis"}</script> <!-- End Jekyll SEO tag --> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-link" viewBox="0 0 24 24"> <title>Link</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link"> <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path> </svg> </symbol> <symbol id="svg-search" viewBox="0 0 24 24"> <title>Search</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-search"> <circle cx="11" cy="11" r="8"></circle><line x1="21" y1="21" x2="16.65" y2="16.65"></line> </svg> </symbol> <symbol id="svg-menu" viewBox="0 0 24 24"> <title>Menu</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-menu"> <line x1="3" y1="12" x2="21" y2="12"></line><line x1="3" y1="6" x2="21" y2="6"></line><line x1="3" y1="18" x2="21" y2="18"></line> </svg> </symbol> <symbol id="svg-arrow-right" viewBox="0 0 24 24"> <title>Expand</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-chevron-right"> <polyline points="9 18 15 12 9 6"></polyline> </svg> </symbol> <symbol id="svg-doc" viewBox="0 0 24 24"> <title>Document</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-file"> <path d="M13 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"></path><polyline points="13 2 13 9 20 9"></polyline> </svg> </symbol> </svg> <div class="side-bar"> <div class="site-header"> <a href="https://depp.github.io/syncfiles/" class="site-title lh-tight"> SyncFiles Documentation </a> <a href="#" id="menu-button" class="site-button"> <svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-menu"></use></svg> </a> </div> <nav role="navigation" aria-label="Main" id="site-nav" class="site-nav"> <ul class="nav-list"><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="https://depp.github.io/syncfiles/tech/" class="nav-list-link">Technical Guide</a><ul class="nav-list "><li class="nav-list-item "><a href="https://depp.github.io/syncfiles/tech/archive-formats" class="nav-list-link">Archive Formats</a></li><li class="nav-list-item "><a href="https://depp.github.io/syncfiles/tech/resource-forks" class="nav-list-link">Resource Forks</a></li><li class="nav-list-item "><a href="https://depp.github.io/syncfiles/tech/finder-info" class="nav-list-link">Finder Info</a></li><li class="nav-list-item active"><a href="https://depp.github.io/syncfiles/tech/apis" class="nav-list-link active">File APIs</a></li><li class="nav-list-item "><a href="https://depp.github.io/syncfiles/tech/filesystems" class="nav-list-link">Filesystems</a></li><li class="nav-list-item "><a href="https://depp.github.io/syncfiles/tech/safe-saving" class="nav-list-link">Safe Saving</a></li></ul></li><li class="nav-list-item"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="https://depp.github.io/syncfiles/" class="nav-list-link">Home</a><ul class="nav-list "></ul></li></ul> </nav> <footer class="site-footer"> This site uses <a href="https://github.com/pmarsceill/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll. </footer> </div> <div class="main" id="top"> <div id="main-header" class="main-header"> <div class="search"> <div class="search-input-wrap"> <input type="text" id="search-input" class="search-input" tabindex="0" placeholder="Search SyncFiles Documentation" aria-label="Search SyncFiles Documentation" autocomplete="off"> <label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#svg-search"></use></svg></label> </div> <div id="search-results" class="search-results"></div> </div> </div> <div id="main-content-wrap" class="main-content-wrap"> <nav aria-label="Breadcrumb" class="breadcrumb-nav"> <ol class="breadcrumb-nav-list"> <li class="breadcrumb-nav-list-item"><a href="https://depp.github.io/syncfiles/tech/">Technical Guide</a></li> <li class="breadcrumb-nav-list-item"><span>File APIs</span></li> </ol> </nav> <div id="main-content" class="main-content" role="main"> <h1 id="file-apis"> <a href="#file-apis" class="anchor-heading" aria-labelledby="file-apis"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> File APIs </h1> <p>Mac OS filesystem APIs evolved as the underlying filesystem semantics changed.</p> <h2 id="pascal-strings"> <a href="#pascal-strings" class="anchor-heading" aria-labelledby="pascal-strings"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Pascal Strings </h2> <p>Prior to Mac OS X, Macintosh APIs used <em>Pascal strings</em> to represent strings. Pascal strings are passed by pointer. The first byte pointed to stores the string length, and the string contents follows. Pascal strings are not null-terminated and not compatible with C-style strings. Note that since the string length is stored in a single byte, these strings cannot be longer than 255 bytes.</p> <p>Compilers for Mac OS support Pascal strings by putting the <code class="language-plaintext highlighter-rouge">\p</code> sequence at the beginning of a string. For example,</p> <div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">const</span> <span class="kt">unsigned</span> <span class="kt">char</span> <span class="n">kFilename</span><span class="p">[]</span> <span class="o">=</span> <span class="s">"\pMy File"</span><span class="p">;</span>
</code></pre></div></div> <p>This is equivalent to:</p> <div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">const</span> <span class="kt">unsigned</span> <span class="kt">char</span> <span class="n">kFilename</span><span class="p">[</span><span class="mi">8</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span>
<span class="mi">7</span><span class="p">,</span> <span class="sc">'M'</span><span class="p">,</span> <span class="sc">'y'</span><span class="p">,</span> <span class="sc">' '</span><span class="p">,</span> <span class="sc">'F'</span><span class="p">,</span> <span class="sc">'i'</span><span class="p">,</span> <span class="sc">'l'</span><span class="p">,</span> <span class="sc">'e'</span>
<span class="p">};</span>
</code></pre></div></div> <p>Pascal strings are encoded using one of the old Macintosh character encodings, such as Mac OS Roman. In some cases, the encoding is assumed to be the system’s encoding, whatever that is. In other cases, the encoding is explicitly specified using a <code class="language-plaintext highlighter-rouge">ScriptCode</code> (although this value is somewhat ambiguous). In other cases still, the actual encoding is ignored and the string is treated as if it were encoded using the Mac OS Roman encoding.</p> <h2 id="early-mac-os"> <a href="#early-mac-os" class="anchor-heading" aria-labelledby="early-mac-os"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Early Mac OS </h2> <p>The filesystem on the very first Macintosh, later called the Mac 128K, did not support folders or directories. Each file was identified by volume ID and name. For example, <code class="language-plaintext highlighter-rouge">OpenDF</code> opens the data fork of a file (presumably, <code class="language-plaintext highlighter-rouge">DF</code> stands for “data fork”—there is a corresponding <code class="language-plaintext highlighter-rouge">OpenRF</code> for the resource fork), and <code class="language-plaintext highlighter-rouge">Create</code> creates a new file.</p> <div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">OSErr</span> <span class="nf">OpenDF</span><span class="p">(</span>
<span class="k">const</span> <span class="kt">unsigned</span> <span class="kt">char</span> <span class="o">*</span> <span class="n">fileName</span><span class="p">,</span>
<span class="kt">short</span> <span class="n">vRefNum</span><span class="p">,</span>
<span class="kt">short</span> <span class="o">*</span> <span class="n">refNum</span><span class="p">);</span>
<span class="n">OSErr</span> <span class="nf">Create</span><span class="p">(</span>
<span class="k">const</span> <span class="kt">unsigned</span> <span class="kt">char</span> <span class="o">*</span> <span class="n">fileName</span><span class="p">,</span>
<span class="kt">short</span> <span class="n">vRefNum</span><span class="p">,</span>
<span class="n">OSType</span> <span class="n">creator</span><span class="p">,</span>
<span class="n">OSType</span> <span class="n">fileType</span><span class="p">);</span>
</code></pre></div></div> <p>Filenames have a maximum length of 63 characters and are case insensitive. Systems from this era did not support multiple character encodings, so the encoding did not need to be specified. Note that the 63-character limit is an API limit, and common filesystems have a lower, 31-character limit.</p> <p>You should not be using this API unless you are targeting <em>extremely</em> old Macintosh systems, like the Mac 128K. This API became obsolete with the introduction of 128K ROMs with the Mac Plus in 1986.</p> <p>This API is not part of Carbon and cannot be used on Mac OS X.</p> <h3 id="swapping-floppy-disks"> <a href="#swapping-floppy-disks" class="anchor-heading" aria-labelledby="swapping-floppy-disks"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Swapping Floppy Disks </h3> <p>During this era, it was common to swap floppy disks while a program was running. You can run a program from one disk and save files on another disk. When a program tries to access a file that’s on a different disk, the operating system ejects the current disk and prompts the user to insert the correct disk. This happens automatically; programs do not need to include any code to make this possible.</p> <h3 id="compatibility-with-hfs"> <a href="#compatibility-with-hfs" class="anchor-heading" aria-labelledby="compatibility-with-hfs"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Compatibility with HFS </h3> <p>Old applications written to use this API continue to work after files after the introduction of the hierarchical filesystem. The way this happens is through something called <em>working directories</em>.</p> <p>A working directory is the combination of a volume ID and a directory ID, and it can be used in place of a volume ID in the filesystem API. The intent is that old code which only uses volume IDs can be used to save files in different locations on the filesystem. For example, if an old application creates a “save file” dialog box, instead of a volume ID, the dialog box returns a working directory pointing to the directory where the user chose to save the file.</p> <h2 id="hierarchical-api"> <a href="#hierarchical-api" class="anchor-heading" aria-labelledby="hierarchical-api"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Hierarchical API </h2> <p>Alongside Apple’s first hard disk for the Macintosh, the operating system introduced a new filesystem (HFS) which supported directories, and this required a new API. Instead of <code class="language-plaintext highlighter-rouge">OpenDF</code>, programs now call <code class="language-plaintext highlighter-rouge">HOpenDF</code> to the data fork of a file, and call <code class="language-plaintext highlighter-rouge">HCreate</code> instead of <code class="language-plaintext highlighter-rouge">Create</code>. Presumably, “H” stands for “hierarchical”.</p> <div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">OSErr</span> <span class="nf">HOpenDF</span><span class="p">(</span>
<span class="kt">short</span> <span class="n">vRefNum</span><span class="p">,</span>
<span class="kt">long</span> <span class="n">dirID</span><span class="p">,</span>
<span class="k">const</span> <span class="kt">unsigned</span> <span class="kt">char</span> <span class="o">*</span> <span class="n">fileName</span><span class="p">,</span>
<span class="n">SInt8</span> <span class="n">permission</span><span class="p">,</span>
<span class="kt">short</span> <span class="o">*</span> <span class="n">refNum</span><span class="p">);</span>
<span class="n">OSErr</span> <span class="nf">HCreate</span><span class="p">(</span>
<span class="kt">short</span> <span class="n">vRefNum</span><span class="p">,</span>
<span class="kt">long</span> <span class="n">dirID</span><span class="p">,</span>
<span class="k">const</span> <span class="kt">unsigned</span> <span class="kt">char</span> <span class="o">*</span> <span class="n">fileName</span><span class="p">,</span>
<span class="n">OSType</span> <span class="n">creator</span><span class="p">,</span>
<span class="n">OSType</span> <span class="n">fileType</span><span class="p">);</span>
</code></pre></div></div> <p>In this API, files are identified by volume ID, the directory ID within that volume, and the filename within that directory. The encoding is not specified, and presumably, files will be created using the system’s default character encoding.</p> <h2 id="fsspec-api"> <a href="#fsspec-api" class="anchor-heading" aria-labelledby="fsspec-api"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> FSSpec API </h2> <p>Mac System 7 introduces the FSSPec API. It does not change semantics, but provides a simple data structure which is used to store the volume ID, directory ID, and filename. This structure is called <code class="language-plaintext highlighter-rouge">FSSpec</code>.</p> <div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">struct</span> <span class="n">FSSpec</span> <span class="p">{</span>
<span class="kt">short</span> <span class="n">vRefNum</span><span class="p">;</span>
<span class="kt">long</span> <span class="n">parID</span><span class="p">;</span>
<span class="kt">unsigned</span> <span class="kt">char</span> <span class="n">name</span><span class="p">[</span><span class="mi">64</span><span class="p">];</span>
<span class="p">};</span>
</code></pre></div></div> <p>Functions which use an <code class="language-plaintext highlighter-rouge">FSSpec</code> are named with the <code class="language-plaintext highlighter-rouge">FSp</code> prefix. These functions are preferred for over the previous versions for their simplicity. For example, <code class="language-plaintext highlighter-rouge">FSpOpenDF</code>, which opens a file’s data fork, and <code class="language-plaintext highlighter-rouge">FSpCreate</code>, which creates a new file:</p> <div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">OSErr</span> <span class="nf">FSpOpenDF</span><span class="p">(</span>
<span class="k">const</span> <span class="n">FSSpec</span> <span class="o">*</span> <span class="n">spec</span><span class="p">,</span>
<span class="n">SInt8</span> <span class="n">permission</span><span class="p">,</span>
<span class="kt">short</span> <span class="o">*</span> <span class="n">refNum</span><span class="p">);</span>
<span class="n">OSErr</span> <span class="nf">FSpCreate</span><span class="p">(</span>
<span class="k">const</span> <span class="n">FSSpec</span> <span class="o">*</span> <span class="n">spec</span><span class="p">,</span>
<span class="n">OSType</span> <span class="n">creator</span><span class="p">,</span>
<span class="n">OSType</span> <span class="n">fileType</span><span class="p">,</span>
<span class="n">ScriptCode</span> <span class="n">scriptTag</span><span class="p">);</span>
</code></pre></div></div> <p>Note that the character encoding is specified when creating a file, using the <code class="language-plaintext highlighter-rouge">scriptTag</code> parameter (although technically, this does not completely specify an encoding). The character encoding is not specified when opening a file, instead, the encoding is ignored and treated as if it were the Mac OS Roman encoding.</p> <p>This API <em>preserves</em> the encoding used for filenames, but you only need the correct bytestring to refer to existing files.</p> <p>Starting in Mac OS X 10.4, this API and other APIs before it are marked as deprecated.</p> <h2 id="fsref-api"> <a href="#fsref-api" class="anchor-heading" aria-labelledby="fsref-api"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> FSRef API </h2> <p>Mac OS 9 introduces a new opaque alternative to <code class="language-plaintext highlighter-rouge">FSSpec</code> called <code class="language-plaintext highlighter-rouge">FSRef</code>. You can use an <code class="language-plaintext highlighter-rouge">FSRef</code> to refer to an existing file, but there is no way to get any information from an <code class="language-plaintext highlighter-rouge">FSRef</code> without invoking the filesystem API. The <code class="language-plaintext highlighter-rouge">FSRef</code> is not a drop-in replacement for <code class="language-plaintext highlighter-rouge">FSSpec</code>, beceause a <code class="language-plaintext highlighter-rouge">FSRef</code> must refer to an existing file, and therefore, cannot be used to create a new file.</p> <div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">struct</span> <span class="n">FSRef</span> <span class="p">{</span>
<span class="n">UInt8</span> <span class="n">hidden</span><span class="p">[</span><span class="mi">80</span><span class="p">];</span>
<span class="p">};</span>
</code></pre></div></div> <p>The <code class="language-plaintext highlighter-rouge">FSRef</code> structure is private to an application and cannot be assumed to be valid if the file is moved/renamed, if the volume is unmounted and remounted, or if the structure is passed to another process. We can speculate that the <code class="language-plaintext highlighter-rouge">FSRef</code> structure contains information about a file like its filesystem inode, which can be used to look up the file name.</p> <p>You can convert an <code class="language-plaintext highlighter-rouge">FSSpec</code> to an <code class="language-plaintext highlighter-rouge">FSRef</code>, although this will fail if the file does not exist:</p> <div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">OSErr</span> <span class="nf">FSpMakeFSRef</span><span class="p">(</span>
<span class="k">const</span> <span class="n">FSSpec</span> <span class="o">*</span> <span class="n">source</span><span class="p">,</span>
<span class="n">FSRef</span> <span class="o">*</span> <span class="n">newRef</span><span class="p">);</span>
</code></pre></div></div> <p>The <code class="language-plaintext highlighter-rouge">FSRef</code> API has some other differences. For example, when you open a file, you specify the name of the fork you want to open. Previous APIs used different functions for opening the data fork and the resource fork. File names are now specified as Unicode strings encoded with UTF-16.</p> <div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">OSErr</span> <span class="nf">FSOpenFork</span><span class="p">(</span>
<span class="k">const</span> <span class="n">FSRef</span> <span class="o">*</span> <span class="n">ref</span><span class="p">,</span>
<span class="n">UniCharCount</span> <span class="n">forkNameLength</span><span class="p">,</span>
<span class="k">const</span> <span class="n">UniChar</span> <span class="o">*</span> <span class="n">forkName</span><span class="p">,</span>
<span class="n">SInt8</span> <span class="n">permissions</span><span class="p">,</span>
<span class="n">SInt16</span> <span class="o">*</span> <span class="n">forkRefNum</span><span class="p">);</span>
<span class="n">OSErr</span> <span class="nf">FSCreateFileUnicode</span><span class="p">(</span>
<span class="k">const</span> <span class="n">FSRef</span> <span class="o">*</span> <span class="n">parentRef</span><span class="p">,</span>
<span class="n">UniCharCount</span> <span class="n">nameLength</span><span class="p">,</span>
<span class="k">const</span> <span class="n">UniChar</span> <span class="o">*</span> <span class="n">name</span><span class="p">,</span>
<span class="n">FSCatalogInfoBitmap</span> <span class="n">whichInfo</span><span class="p">,</span>
<span class="k">const</span> <span class="n">FSCatalogInfo</span> <span class="o">*</span> <span class="n">catalogInfo</span><span class="p">,</span>
<span class="n">FSRef</span> <span class="o">*</span> <span class="n">newRef</span><span class="p">,</span>
<span class="n">FSSpec</span> <span class="o">*</span> <span class="n">newSpec</span><span class="p">);</span>
</code></pre></div></div> <p>This API is a part of Carbon. Carbon was never ported to 64-bit architectures, and was deprecated in Mac OS X 10.8. The last version that supports this API is macOS 10.14, which is the last version of macOS that supports 32-bit programs.</p> <h2 id="unix-api"> <a href="#unix-api" class="anchor-heading" aria-labelledby="unix-api"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Unix API </h2> <p>Mac OS X brought us the Unix APIs:</p> <div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kt">int</span> <span class="nf">open</span><span class="p">(</span>
<span class="k">const</span> <span class="kt">char</span> <span class="o">*</span> <span class="n">pathname</span><span class="p">,</span>
<span class="kt">int</span> <span class="n">flags</span><span class="p">,</span>
<span class="p">...);</span>
<span class="kt">int</span> <span class="nf">openat</span><span class="p">(</span>
<span class="kt">int</span> <span class="n">fd</span><span class="p">,</span>
<span class="k">const</span> <span class="kt">char</span> <span class="o">*</span> <span class="n">pathname</span><span class="p">,</span>
<span class="kt">int</span> <span class="n">flags</span><span class="p">,</span>
<span class="p">...);</span>
</code></pre></div></div> <p>The <code class="language-plaintext highlighter-rouge">openat</code> call is available from Mac OS 10.10 onwards.</p> <p>Strings are now null-terminated C strings, which are interpreted as UTF-8. Mac OS filesystems do not support arbitrary bytestrings as filenames. If you try to create a file with <code class="language-plaintext highlighter-rouge">open</code> with a filename that is not supported by the filesystem, the system call will fail and set <code class="language-plaintext highlighter-rouge">errno</code> to <code class="language-plaintext highlighter-rouge">EILSEQ</code> (92). This is not documented in the man page for <code class="language-plaintext highlighter-rouge">open</code>.</p> <h3 id="forks-on-unix"> <a href="#forks-on-unix" class="anchor-heading" aria-labelledby="forks-on-unix"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Forks on Unix </h3> <p>The resource fork can be accessed as if it were a separate file. To access the resource fork, append <code class="language-plaintext highlighter-rouge">/rsrc</code> or <code class="language-plaintext highlighter-rouge">/..namedfork/rsrc</code> to the file path. This allows you to view resource fork data through ordinary Unix APIs or with Unix command-line utilities like <code class="language-plaintext highlighter-rouge">hexdump</code> and <code class="language-plaintext highlighter-rouge">ls</code>.</p> <p>Linux also allows you to access the resource fork by appending <code class="language-plaintext highlighter-rouge">/rsrc</code> to the file path, for filesystems that support resource forks.</p> <h3 id="extended-attributes"> <a href="#extended-attributes" class="anchor-heading" aria-labelledby="extended-attributes"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Extended Attributes </h3> <p>Starting in version 10.4, Mac OS X provides an interface for accessing extended attributes on a file.</p> <div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kt">ssize_t</span> <span class="nf">getxattr</span><span class="p">(</span>
<span class="k">const</span> <span class="kt">char</span> <span class="o">*</span> <span class="n">path</span><span class="p">,</span>
<span class="k">const</span> <span class="kt">char</span> <span class="o">*</span> <span class="n">name</span><span class="p">,</span>
<span class="kt">void</span> <span class="o">*</span> <span class="n">value</span><span class="p">,</span>
<span class="kt">size_t</span> <span class="n">size</span><span class="p">,</span>
<span class="n">u_int32_t</span> <span class="n">position</span><span class="p">,</span>
<span class="kt">int</span> <span class="n">options</span><span class="p">);</span>
</code></pre></div></div> <p>The resource fork is presented as an extended attribute with the name <code class="language-plaintext highlighter-rouge">com.apple.ResourceFork</code>. Since resource forks can be as much as 16 MiB in size, the <code class="language-plaintext highlighter-rouge">getxattr</code> function provides a way to read portions of the resource fork without having to read the entire fork.</p> <p>Finder info is contained in an attribute named <code class="language-plaintext highlighter-rouge">com.apple.FinderInfo</code>.</p> <h2 id="aliases-and-bookmarks"> <a href="#aliases-and-bookmarks" class="anchor-heading" aria-labelledby="aliases-and-bookmarks"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Aliases and Bookmarks </h2> <p>Mac OS also provides facilities to store a reference to a file. These references are designed to be durable, and work even if the file is moved and renamed. These references work by containing various pieces of metadata about the file. If the file is moved, the metadata can be used to find it again.</p> <p>On older Mac OS systems, these records are called <em>aliases</em> and you can create them using the alias manager APIs, which are available starting in System 7.</p> <p>In Cocoa, these records are called <em>bookmarks</em>.</p> <p>The main use of aliases and bookmarks is to store references to files in the “recently used files” menu option in applications.</p> </div> </div> <div class="search-overlay"></div> </div> </body> </html>
Reference in New Issue View Git Blame Copy Permalink