Repository navigation
Expand file tree
/
Copy pathfreebsd-notifyd-plan.html
More file actions
528 lines (448 loc) · 45.8 KB
/
Copy pathfreebsd-notifyd-plan.html
File metadata and controls
528 lines (448 loc) · 45.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>FreeBSD notifyd — porting plan</title>
<style>
:root {
--bg: #fbfbf8;
--fg: #1a1a1a;
--muted: #555;
--accent: #b03000;
--accent2: #0a4d68;
--ok: #1f7a1f;
--warn: #b06800;
--bad: #b00020;
--code-bg: #f0ece4;
--rule: #d6cfc0;
--card: #fff;
}
html { -webkit-text-size-adjust: 100%; }
body { margin: 0 auto; max-width: 980px; padding: 2.5rem 1.5rem 6rem;
font: 16px/1.55 -apple-system, BlinkMacSystemFont, "SF Pro Text", system-ui, sans-serif;
color: var(--fg); background: var(--bg); }
h1 { font-size: 2rem; line-height: 1.2; margin: 0 0 .25rem; }
h2 { font-size: 1.4rem; margin: 2.5rem 0 .75rem; padding-bottom: .25rem; border-bottom: 2px solid var(--rule); }
h3 { font-size: 1.15rem; margin: 1.75rem 0 .5rem; color: var(--accent2); }
h4 { margin: 1.25rem 0 .35rem; }
.subtitle { color: var(--muted); font-size: 1.05rem; margin: 0 0 2rem; }
code, pre, kbd { font-family: "SF Mono", Menlo, Consolas, monospace; }
code { background: var(--code-bg); padding: 1px 5px; border-radius: 3px; font-size: .9em; }
pre { background: var(--code-bg); padding: .85rem 1rem; border-radius: 6px;
overflow-x: auto; font-size: .82rem; line-height: 1.45;
border-left: 3px solid var(--accent2); }
pre code { background: none; padding: 0; }
pre.shell { border-left-color: var(--ok); }
pre.plist { border-left-color: var(--accent); }
pre.warn-pre { border-left-color: var(--warn); background: #fff5e6; }
a { color: var(--accent2); }
a:hover { color: var(--accent); }
.tldr { background: var(--card); border: 1px solid var(--rule); border-left: 4px solid var(--accent2);
padding: 1rem 1.25rem; border-radius: 6px; margin-bottom: 2rem; }
.tldr h3 { margin-top: 0; color: var(--accent2); }
.pill { display: inline-block; font-size: .72rem; padding: 1px 8px; border-radius: 999px;
background: #eee; color: #333; margin-left: .35rem; vertical-align: middle;
font-weight: 600; letter-spacing: .02em; }
.pill.ok { background: #d8efd8; color: var(--ok); }
.pill.warn { background: #f6e4cb; color: var(--warn); }
.pill.bad { background: #f5d0d6; color: var(--bad); }
.pill.info { background: #d6e6f3; color: var(--accent2); }
.grid { display: grid; gap: 1rem; grid-template-columns: 1fr 1fr; margin: 1rem 0; }
@media (max-width: 700px) { .grid { grid-template-columns: 1fr; } }
.card { background: var(--card); border: 1px solid var(--rule); border-radius: 6px;
padding: 1rem 1.1rem; }
.card h4 { margin-top: 0; }
.phase { background: var(--card); border: 1px solid var(--rule); border-radius: 6px;
padding: 1.2rem 1.4rem; margin: 1rem 0; }
.phase h3 { margin-top: 0; }
table { border-collapse: collapse; width: 100%; margin: 1rem 0; font-size: .92rem; }
th, td { text-align: left; padding: .5rem .65rem; border-bottom: 1px solid var(--rule); vertical-align: top; }
th { background: #eee5d6; }
tr:nth-child(even) td { background: #faf6ed; }
blockquote { margin: 1rem 0; padding: .5rem 1rem; border-left: 3px solid var(--accent);
background: #fff8f3; color: #333; }
.footnote { font-size: .85rem; color: var(--muted); }
ol li, ul li { margin: .25rem 0; }
.nav { position: sticky; top: 0; background: var(--bg); margin: -2.5rem -1.5rem 2rem;
padding: .75rem 1.5rem; border-bottom: 1px solid var(--rule);
font-size: .88rem; z-index: 10; }
.nav a { margin-right: .9rem; text-decoration: none; }
.filename { color: var(--accent); font-family: "SF Mono", Menlo, Consolas, monospace; font-size: .9em; }
.verdict { font-weight: 600; }
.verdict.go { color: var(--ok); }
.verdict.maybe { color: var(--warn); }
.verdict.no { color: var(--bad); }
hr { border: 0; border-top: 1px dashed var(--rule); margin: 2rem 0; }
.resolved { background: #ecf7ec; border-left: 4px solid var(--ok); padding: .8rem 1rem; margin: 1rem 0; border-radius: 0 6px 6px 0; }
.resolved strong { color: var(--ok); }
.risk { background: #fff5e6; border-left: 4px solid var(--warn); padding: .8rem 1rem; margin: 1rem 0; border-radius: 0 6px 6px 0; }
.risk strong { color: var(--warn); }
.ascii-diagram { font-family: "SF Mono", Menlo, Consolas, monospace; font-size: .82rem; line-height: 1.3; white-space: pre; background: var(--code-bg); padding: 1rem; border-radius: 6px; overflow-x: auto; }
.step-num { display: inline-block; width: 1.6em; height: 1.6em; line-height: 1.6em; text-align: center; background: var(--accent); color: white; border-radius: 50%; font-weight: 700; font-size: .85em; margin-right: .35em; }
.open-q { background: #fff8d6; border: 1px solid #e5d76b; padding: .8rem 1rem; margin: 1rem 0; border-radius: 6px; font-size: .92rem; }
.open-q strong { color: #7a5e00; }
</style>
</head>
<body>
<nav class="nav">
<a href="#tldr">Status</a>
<a href="#goal">Goal</a>
<a href="#repo">Repo</a>
<a href="#arch">Architecture</a>
<a href="#paths">Install paths</a>
<a href="#decisions">Decisions</a>
<a href="#files">File-by-file</a>
<a href="#bsd-wins">FreeBSD wins</a>
<a href="#usecases">Use cases (gershwin)</a>
<a href="#integration">launchd integration</a>
<a href="#license">License</a>
<a href="#phases">Phases</a>
<a href="#open">Open questions</a>
</nav>
<h1>FreeBSD notifyd — porting plan</h1>
<p class="subtitle">A FreeBSD-only port of Apple's <code>notifyd</code> + <code>libnotify</code> — Apple's lightweight named-event pub/sub bus. Retains Mach IPC end-to-end: libnotify connects to notifyd via a MIG-served Mach service <code>com.apple.notifyd</code>; preserves the libnotify C API surface so Apple-derived applications (gershwin desktop apps, ported third-party Cocoa apps) Just Work without source changes. Companion to <a href="freebsd-launchd-plan.html">launchd</a>, <a href="nextbsd-configd-plan.html">configd</a>, <a href="freebsd-kmodloader-plan.html">kmodloader</a>, <a href="freebsd-asl-plan.html">asl</a>.</p>
<p><span class="pill info">Filed under: <code>freebsd-launchd-mach</code> (v2) effort</span> <span class="pill ok">SHIPPED</span></p>
<div class="tldr">
<h3>Revision 2026-05-23</h3>
<p>This plan originally targeted the sibling <code>freebsd-launchd</code> (AF_UNIX / GNUstep Distributed Objects) repo. Refactored 2026-05-23 to target the <code>freebsd-launchd-mach</code> (v2) Mach-IPC track. notifyd has already <strong>SHIPPED</strong> in this repo's Phase J1 (<code>libnotify</code>) + Phase J2 iter 1 (<code>notifyd</code> daemon) — Mach IPC retained throughout (<code>DISPATCH_SOURCE_TYPE_MACH_RECV</code> via libdispatch's Mach backend, as documented in the libxpc <code>libdispatch-mach</code> spike). Sections below describing "future work" now describe shipped work; the architecture-decision sentences have been flipped from DO/AF_UNIX to MIG/Mach.</p>
</div>
<section id="tldr" class="tldr">
<h3>Status: <span class="pill ok">SHIPPED</span> — Phase J1 (libnotify) + Phase J2 iter 1 (notifyd daemon)</h3>
<ul>
<li><strong>Repo:</strong> <a href="https://github.com/pkgdemon/freebsd-launchd-mach">github.com/pkgdemon/freebsd-launchd-mach</a> (v2, Mach-IPC track) — <strong>monorepo</strong>. notifyd source under <code>src/Libnotify/</code>, alongside <code>src/launchd/</code>, <code>src/syslog/</code>, <code>src/libxpc/</code>, <code>src/libdispatch/</code>, <code>src/libCoreFoundation/</code>. Single build pipeline (<code>build.sh</code>), single CI, single boot test.</li>
<li><strong>Mission:</strong> give gershwin and any Apple-derived apps the named-event pub/sub bus they expect. Apps call <code>notify_post()</code>, <code>notify_register_dispatch()</code>, <code>notify_get_state()</code> — same C API — and the daemon does the fan-out. Promotes cross-process event coordination from "build a bespoke channel each time" to "just pick a name."</li>
<li><strong>Source:</strong> Apple <code>Libnotify-98.5</code> (latest tag at <code>apple-oss-distributions/Libnotify</code>, APSL). 48 source files, ~17k LOC. 12 files have <code><mach/></code> includes; 2 MIG <code>.defs</code> files (<code>notify_ipc.defs</code>, <code>notify_old_ipc.defs</code>). On the v2 track these are <em>kept</em> — Mach IPC is the substrate.</li>
<li><strong>Why this shipped:</strong> ASL's libsystem_asl emits notifyd posts (<code>com.apple.system.logger</code>) on every log write; configd, PowerManagement, IPConfiguration, DiskArbitration, IOKitUser all register for / post named events. With Mach IPC + libxpc + libdispatch (incl. <code>DISPATCH_SOURCE_TYPE_MACH_RECV</code>) all working, notifyd lands as a thin MIG server on top of the existing substrate. <strong>Built in Phase J1/J2 alongside ASL.</strong></li>
<li><strong>Mach IPC retained.</strong> libnotify uses Mach ports for the daemon connection (MIG client stubs from <code>notify_ipc.defs</code>); <code>shm_open(2)</code> + <code>mmap(2)</code> for the shared state-value pages (preserves Apple's "reads are zero-IPC" performance characteristic).</li>
<li><strong>Event loop:</strong> libdispatch with <code>DISPATCH_SOURCE_TYPE_MACH_RECV</code> on notifyd's MIG service port (the libxpc spike documented why we needed this — libdispatch's Mach backend now provides it on FreeBSD). <code>DISPATCH_SOURCE_TYPE_VNODE</code> for path-watch notifications (same as Apple — <code>pathwatch.c</code> already uses kqueue under the hood).</li>
<li><strong>libnotify C API preserved byte-for-byte.</strong> <code>notify_post</code>, <code>notify_register_dispatch</code>, <code>notify_register_signal</code>, <code>notify_register_file_descriptor</code>, <code>notify_register_check</code>, <code>notify_get_state</code>, <code>notify_set_state</code>, <code>notify_cancel</code> all keep their existing signatures and semantics. Apple-derived apps link our <code>libnotify.so</code> without source changes.</li>
<li><strong>All delivery types retained including <code>NOTIFY_TYPE_PORT</code></strong> (Mach-port wakeup) — Mach IPC is the substrate, so the port-delivery type is the natural one. <code>NOTIFY_TYPE_DISPATCH</code>, <code>NOTIFY_TYPE_SIGNAL</code>, <code>NOTIFY_TYPE_FD</code>, <code>NOTIFY_TYPE_CHECK</code> all preserved as well.</li>
<li><strong>Licensing:</strong> Apple's source is APSL 1.1 (older variant; APSL 2.0 in newer files within the repo). FSF-approved free software; per-file headers preserved on Apple-derived files; our top-level repo stays BSD-2-Clause.</li>
</ul>
</section>
<h2 id="goal">1. Goal & non-goals</h2>
<h3>1.1 Goal</h3>
<p>Provide a working <code>libnotify</code> + <code>notifyd</code> on FreeBSD so Apple-derived apps (gershwin desktop, ported Cocoa apps, third-party Apple-OSS-distributions tools) can use named pub/sub events without porting work. Replicate the API surface byte-for-byte; retain Apple's Mach-IPC substrate (libnotify ↔ notifyd via MIG over <code>mach_msg</code>); use POSIX <code>shm_open(2)</code>+<code>mmap(2)</code> for the shared state-value pages (the one Mach-specific mechanism with no clean equivalent on FreeBSD's Mach port — same end result, portable substrate). Preserve the performance characteristic that <em>reads of state values are zero-IPC</em> — that's what makes notifyd fundamentally different from a sockets-only pub/sub system.</p>
<h3>1.2 Non-goals (this iteration)</h3>
<ul>
<li><strong>No DTrace probes.</strong> <code>notify_probes.d</code> is dropped. FreeBSD has DTrace but the probe definitions are Apple-specific.</li>
<li><strong>No iOS/iPadOS configs.</strong> <code>notify.conf.iOSSimulator</code>, <code>notify.conf.iPhone</code> dropped on import.</li>
<li><strong>No sandbox profile.</strong> <code>com.apple.notifyd.sb</code> is sandbox(7); FreeBSD has Capsicum but the policy doesn't translate. Hardening pass later.</li>
<li><strong>No app entitlements.</strong> <code>entitlements.plist</code>, <code>notifyutil_entitlements.plist</code> are macOS code-signing concerns; n/a here.</li>
<li><strong>No XCTest harness.</strong> <code>Libnotify.xcodeproj</code>, <code>xctests/</code>, <code>notifyd-xctests/</code> dropped — Xcode-only. We rebuild a minimal test corpus on top of FreeBSD's <code>kyua</code> or just shell scripts.</li>
</ul>
<h2 id="repo">2. Repository</h2>
<p>Monorepo, same as the other ports on the v2 track. notifyd source lives under <code>src/Libnotify/</code> at the top of <code>freebsd-launchd-mach</code>:</p>
<pre><code>freebsd-launchd-mach/
├── src/launchd/ launchd Apple-imported source
├── src/syslog/ Apple syslog-imported source (ASL)
├── src/libxpc/ libxpc (Mach IPC client/server)
├── src/libdispatch/ libdispatch (incl. Mach backend: MACH_RECV, MACH_SEND)
├── src/libCoreFoundation/ CoreFoundation port
├── src/Libnotify/ Apple Libnotify-imported source (this plan)
│ ├── libnotify.{c,h} the libnotify client library — API surface
│ ├── notify.h public API header
│ ├── notify_keys.h public well-known notification names
│ ├── notify_client.c client-side state management
│ ├── notify_internal.h
│ ├── notify_private.h
│ ├── notify_ipc.defs MIG IDL (current)
│ ├── notify_old_ipc.defs MIG IDL (legacy, for back-compat clients)
│ ├── table.{c,h} hash-table for token registry
│ └── notifyd/ the notifyd daemon
│ ├── notifyd.{c,h} daemon main, dispatch loop
│ ├── service.{c,h} service registration + name table
│ ├── notify_proc.c per-client process tracking
│ ├── pathwatch.{c,h} path-watch notifications via kqueue
│ └── notify.conf (MacOSX flavor; iOS variants dropped)
└── build.sh top-level: builds libnotify + notifyd alongside ASL + libxpc + libdispatch
</code></pre>
<h2 id="arch">3. Architecture</h2>
<div class="ascii-diagram"> +------------------------+
| publisher process |
| notify_post("name") |
+------------+-----------+
| (MIG: notify_server_post over mach_msg)
v
+----------------+ +--------+--------+ +--------------------+
| /etc/notify. |-->| notifyd |<-->| /var/run/notifyd/ |
| conf | | (MIG server, | | state-pages |
| (early-access | | libdispatch | | (POSIX shm; one |
| table) | | MACH_RECV) | | uint64 per state |
+----------------+ +--------+--------+ | value, atomically |
| | updated) |
| (delivery +--------------------+
| per token type:
v _PORT | _DISPATCH | _SIGNAL | _FD)
+----------------+----------------+
| subscribers |
| (libnotify clients in apps) |
| token = notify_register_*("name", ...)|
+---------------------------------+
Mach service: com.apple.notifyd
(bootstrap_check_in by notifyd; bootstrap_look_up by libnotify)</div>
<h3>3.1 The state-value optimization (load-bearing)</h3>
<p>notifyd's defining feature versus a generic pub/sub system: <strong>reads of state values are <em>zero-IPC</em>.</strong> Apple does this with shared-memory pages — when a process registers for a name with state, it's mapped a page containing the state's <code>uint64_t</code> slot. The daemon writes the slot directly when state changes; client reads are a memory load. No syscall, no IPC roundtrip.</p>
<p>This is why notifyd works for high-frequency state (volume level updates 60Hz, network reachability checks per HTTP request, etc.) where a sockets-roundtrip-per-read would be too slow.</p>
<p><strong>FreeBSD port preserves this</strong>: replace Apple's Mach-allocated shared pages with <code>shm_open(2)</code> POSIX shared memory (the one place we substitute a portable POSIX primitive for a Mach VM primitive — Apple's <code>vm_allocate</code>+port-handoff has no clean equivalent on FreeBSD's mach.ko port, but the end-user semantic — "shared page, daemon writes, clients read with no syscall" — is identical). The daemon allocates one or more shm segments holding the state-value array; clients <code>mmap()</code> them read-only at registration time. Daemon writes go through atomic store intrinsics (<code>__atomic_store_n</code>) so torn reads aren't possible.</p>
<h3>3.2 Mach IPC: MIG over mach_msg</h3>
<p>The daemon-client channel uses Mach ports — see <code>notify_ipc.defs</code> + <code>notify_old_ipc.defs</code> (two MIG IDLs; old + current). Both are kept on the v2 track:</p>
<ul>
<li><strong>Server side:</strong> notifyd registers the Mach service <code>com.apple.notifyd</code> via <code>bootstrap_check_in</code> at startup. The MIG-generated server stubs (<code>notify_ipc_server.c</code>) dispatch incoming <code>mach_msg</code> requests to the daemon's handler functions (<code>_notifyd_server_post</code>, <code>_notifyd_server_register_*</code>, <code>_notifyd_server_get_state</code>, <code>_notifyd_server_set_state</code>, etc.). The receive-side runs on a libdispatch <code>DISPATCH_SOURCE_TYPE_MACH_RECV</code> source attached to the service port.</li>
<li><strong>Client side:</strong> <code>libnotify.c</code> calls the MIG-generated client stubs (<code>notify_ipc_user.c</code>); each stub builds a <code>mach_msg</code>, sends it to the service port (obtained once via <code>bootstrap_look_up("com.apple.notifyd")</code>), and waits on the reply port. The public <code>notify_*</code> API remains identical to Apple's; the MIG layer is unchanged from Apple's source.</li>
<li><strong>Notification delivery</strong> (subscriber wakeup): preserved per-type, all four supported:
<ul>
<li><code>NOTIFY_TYPE_PORT</code> — daemon sends an empty <code>mach_msg</code> to a port the subscriber registered. Native Mach mechanism; no translation needed.</li>
<li><code>NOTIFY_TYPE_DISPATCH</code> — daemon sends a Mach message to a port driving a libdispatch source (<code>DISPATCH_SOURCE_TYPE_MACH_RECV</code>) in the subscriber. Same path Apple takes.</li>
<li><code>NOTIFY_TYPE_SIGNAL</code> — daemon <code>kill(pid, sig)</code>s the subscriber. Portable as-is.</li>
<li><code>NOTIFY_TYPE_FD</code> — daemon writes a byte to a pipe the subscriber holds the read end of. Portable as-is.</li>
</ul>
</li>
</ul>
<h3>3.3 Path-watch notifications</h3>
<p>notifyd implements file-path-watch notifications: subscribe to a <strong>path</strong>, get woken when the file changes. Apple's <code>pathwatch.c</code> uses kqueue under the hood (Darwin natively); we keep the implementation as-is. <code>DISPATCH_SOURCE_TYPE_VNODE</code> in libdispatch.</p>
<h3>3.4 Event sources (libdispatch)</h3>
<table>
<thead><tr><th>Source type</th><th>Watches</th><th>Reaction</th></tr></thead>
<tbody>
<tr><td><code>DISPATCH_SOURCE_TYPE_MACH_RECV</code></td><td>notifyd's MIG service port (<code>com.apple.notifyd</code>, registered via <code>bootstrap_check_in</code>)</td><td>incoming <code>mach_msg</code> is dispatched through the MIG-generated server stubs (<code>notify_ipc_server.c</code>) to the daemon's handler functions</td></tr>
<tr><td><code>DISPATCH_SOURCE_TYPE_VNODE</code></td><td>each registered path</td><td>fire path-changed notification to subscribers</td></tr>
<tr><td><code>DISPATCH_SOURCE_TYPE_PROC</code></td><td>each registered client PID</td><td>auto-cancel registrations on <code>DISPATCH_PROC_EXIT</code> (don't deliver to dead clients)</td></tr>
<tr><td><code>DISPATCH_SOURCE_TYPE_VNODE</code></td><td><code>/etc/notify.conf</code></td><td>reload early-access table on config change</td></tr>
<tr><td><code>DISPATCH_SOURCE_TYPE_SIGNAL</code></td><td>SIGTERM, SIGHUP, SIGINFO</td><td>SIGTERM: clean shutdown. SIGHUP: reload conf. SIGINFO: dump stats.</td></tr>
</tbody>
</table>
<h2 id="paths">4. Install paths</h2>
<table>
<thead>
<tr><th>Artifact</th><th>Path</th><th>Why</th></tr>
</thead>
<tbody>
<tr><td><code>notifyd</code> binary</td><td><code>/usr/libexec/notifyd</code></td><td>Daemon not invoked directly. Same tier as <code>/usr/libexec/getty</code>, <code>/usr/libexec/netconfigd</code>.</td></tr>
<tr><td><code>notifyutil</code> CLI</td><td><code>/usr/bin/notifyutil</code></td><td>Admin/dev tool: post a name, watch for posts, set/get state. Standard <code>/usr/bin</code> for user-callable commands.</td></tr>
<tr><td><code>libnotify.so</code></td><td><code>/System/Library/Libraries/libnotify.so</code></td><td>The client library. Apps link against this.</td></tr>
<tr><td>Public headers</td><td><code>/System/Library/Headers/notify.h</code><br><code>/System/Library/Headers/notify_keys.h</code></td><td>Apps include via <code>#include <notify.h></code>.</td></tr>
<tr><td>Mach service</td><td><code>com.apple.notifyd</code></td><td>Per-host daemon connection. notifyd checks in via <code>bootstrap_check_in("com.apple.notifyd")</code>; clients look up via <code>bootstrap_look_up</code>. launchd publishes the service via <code>MachServices</code> in the daemon's plist.</td></tr>
<tr><td>State-page directory</td><td><code>/var/run/notifyd/</code></td><td>Daemon-managed POSIX shm names. Created by daemon at startup.</td></tr>
<tr><td>Config</td><td><code>/etc/notify.conf</code></td><td>Apple's "early-access" table — names that get a state slot allocated at daemon startup so they're available before the publisher posts.</td></tr>
<tr><td>launchd plist</td><td><code>/System/Library/LaunchDaemons/com.apple.notifyd.plist</code></td><td>Project-shipped daemon plist. Uses Apple's canonical label so apps registering for system events match Apple's bootstrap naming.</td></tr>
</tbody>
</table>
<h2 id="decisions">5. Locked architectural decisions</h2>
<table>
<thead>
<tr><th>Decision</th><th>Choice</th></tr>
</thead>
<tbody>
<tr><td>Source baseline</td><td>Apple <code>Libnotify-98.5</code>. APSL. Latest tag.</td></tr>
<tr><td>Mach IPC</td><td>Retained. Both <code>.defs</code> files (<code>notify_ipc.defs</code>, <code>notify_old_ipc.defs</code>) kept; MIG client + server stubs compiled in-tree. Service name <code>com.apple.notifyd</code> published via launchd's <code>MachServices</code> dict.</td></tr>
<tr><td>Shared-memory state pages</td><td>POSIX <code>shm_open(2)</code> + <code>mmap(2)</code> substituted for Apple's <code>vm_allocate</code>+port-handoff. Atomic updates via <code><stdatomic.h></code>. (Same end-user semantic; one Mach VM primitive without a clean FreeBSD-mach.ko equivalent.)</td></tr>
<tr><td>Notification delivery types</td><td>All four preserved: <code>NOTIFY_TYPE_PORT</code> (Mach), <code>NOTIFY_TYPE_DISPATCH</code>, <code>NOTIFY_TYPE_SIGNAL</code>, <code>NOTIFY_TYPE_FD</code>, <code>NOTIFY_TYPE_CHECK</code>.</td></tr>
<tr><td>Public API stability</td><td>All <code>notify_*</code> functions in <code>notify.h</code> keep their signatures and observable semantics. Source compatibility with Apple-derived apps is mandatory.</td></tr>
<tr><td>Event loop</td><td>libdispatch dispatch sources, incl. <code>DISPATCH_SOURCE_TYPE_MACH_RECV</code> (Mach backend on FreeBSD — see the libxpc libdispatch-mach spike for the enabling work).</td></tr>
<tr><td>Path-watch impl</td><td>kqueue (already what Apple does on Darwin; preserved).</td></tr>
<tr><td>License (top-level)</td><td>BSD-2-Clause. Apple's libnotify files retain APSL per-file (mix of 1.1 and 2.0 — preserve whichever the file header carries).</td></tr>
</tbody>
</table>
<h2 id="files">6. File-by-file plan (<code>src/Libnotify/</code>)</h2>
<p>Imported source: Apple <code>Libnotify-98.5</code>. 48 files, ~17k LOC. 12 Mach-tied (retained); 2 MIG <code>.defs</code> (retained).</p>
<h3>6.1 Deleted on import (out-of-scope; Mach files retained)</h3>
<ul>
<li><code>Libnotify.xcodeproj/</code>, <code>xcodeconfig/</code>, <code>xcodescripts/</code>, <code>notifyd/xcodescripts/</code> — Xcode build infra</li>
<li><code>notifyd/com.apple.notifyd.sb</code> — sandbox(7) profile; not portable</li>
<li><code>notifyd/entitlements.plist</code>, <code>notifyutil/notifyutil_entitlements.plist</code> — code-signing entitlements; not portable</li>
<li><code>notifyd/notify.conf.iPhone</code>, <code>notifyd/notify.conf.iOSSimulator</code> — iOS variants</li>
<li><code>notify_probes.d</code> — DTrace probe definitions (Apple-specific)</li>
<li><code>xctests/</code>, <code>notifyd-xctests/</code> — XCTest harnesses</li>
<li><code>notify_private.modulemap</code>, <code>notify.modulemap</code> — Clang module maps for Apple's framework build; not used in our pkg-config-based build</li>
</ul>
<p><strong>Retained (was deleted in the v1 / AF_UNIX-DO plan):</strong> <code>notify_ipc.defs</code>, <code>notify_old_ipc.defs</code>, <code>notify_register_mach_port.3</code>, all Mach-tied <code>.c</code>/<code>.h</code> files. The Mach plumbing is the substrate on the v2 track, not an amputation target.</p>
<h3>6.2 Retained — Phase 2 fate</h3>
<table>
<thead>
<tr><th>File</th><th>Apple LOC</th><th>Action</th><th>Target LOC</th></tr>
</thead>
<tbody>
<tr><td><code>libnotify.c</code></td><td>~3.5k</td><td>Keep IPC layer mostly intact — Mach-port-allocation + MIG-stub-call paths run on FreeBSD via mach.ko + libxpc. Public <code>notify_*</code> API unchanged. Replace only the shared-memory mapping (Apple's <code>vm_allocate</code> + port handoff) with POSIX <code>shm_open</code> + <code>mmap</code>.</td><td>~3.2k</td></tr>
<tr><td><code>notify_client.c</code></td><td>~2k</td><td>Keep. Per-token bookkeeping. Mach-aware; runs unchanged.</td><td>~2k</td></tr>
<tr><td><code>notify_ipc.defs</code>, <code>notify_old_ipc.defs</code></td><td>—</td><td>Keep. MIG IDL files; the FreeBSD <code>mig(1)</code> port generates client + server stubs from these (same as Apple's build).</td><td>—</td></tr>
<tr><td><code>table.{c,h}</code>, <code>table.in.c</code></td><td>~1.5k</td><td>Keep. Hash-table impl for token registry. Pure data structure.</td><td>~1.5k</td></tr>
<tr><td><code>notify.h</code>, <code>notify_keys.h</code>, <code>notify_internal.h</code>, <code>notify_private.h</code></td><td>~1k</td><td>Keep. Public API + internal protocol declarations. All token types (incl. <code>NOTIFY_TYPE_PORT</code>) retained.</td><td>~1k</td></tr>
<tr><td><code>notifyd/notifyd.{c,h}</code></td><td>~2k</td><td>Keep. Mach service-loop init runs on FreeBSD's mach.ko; <code>bootstrap_check_in("com.apple.notifyd")</code> + libdispatch <code>DISPATCH_SOURCE_TYPE_MACH_RECV</code>. Keep config-file load + signal handling.</td><td>~2k</td></tr>
<tr><td><code>notifyd/service.{c,h}</code></td><td>~3k</td><td>Keep. Service registration + name table. Mach-port-based subscriber tracking runs as-is, augmented with <code>DISPATCH_SOURCE_TYPE_PROC</code> for PID-exit cleanup.</td><td>~3k</td></tr>
<tr><td><code>notifyd/notify_proc.c</code></td><td>~1k</td><td>Keep. Per-client process management. Auto-cancel registrations on PROC_EXIT.</td><td>~1k</td></tr>
<tr><td><code>notifyd/pathwatch.{c,h}</code></td><td>~600</td><td>Keep mostly intact. kqueue-based; portable.</td><td>~600</td></tr>
<tr><td><code>notifyutil/notifyutil.c</code></td><td>~700</td><td>Port. The CLI is mostly libnotify-call-and-print; once libnotify works the CLI follows.</td><td>~700</td></tr>
<tr><td><code>notifybench/</code></td><td>~500</td><td>Port. Useful for verifying state-page reads stay zero-IPC after our shm_open swap.</td><td>~500</td></tr>
<tr><td>Manpages (<code>notify*.3</code>, <code>notifyd.8</code>, <code>notifyutil.1</code>)</td><td>—</td><td>Keep intact, incl. <code>notify_register_mach_port.3</code>.</td><td>same</td></tr>
</tbody>
</table>
<p>Total post-port: roughly <strong>16-17k LOC</strong>, ~Apple's pre-port size. On the v2 (Mach-IPC) track we keep nearly all of Apple's source unchanged; only the Mach-VM shared-page handoff is substituted with POSIX shm. Compare: the abandoned v1 (AF_UNIX/DO) plan would have rewritten ~30% of the source to swap the wire layer.</p>
<h2 id="bsd-wins">7. FreeBSD port: substrate parity with Apple (v2 / Mach track)</h2>
<table>
<thead>
<tr><th>Feature</th><th>Apple's notifyd does</th><th>This port (<code>freebsd-launchd-mach</code>)</th></tr>
</thead>
<tbody>
<tr><td>Daemon-client IPC</td><td>Mach ports + MIG-generated stubs (two flavors: current + legacy)</td><td>Identical: Mach ports + MIG-generated stubs (both <code>notify_ipc.defs</code> + <code>notify_old_ipc.defs</code> retained, generated via FreeBSD's <code>mig(1)</code>). Substrate provided by mach.ko + libxpc + libdispatch's Mach backend.</td></tr>
<tr><td>State-value pages</td><td>Mach <code>vm_allocate</code> + port handoff for shared memory</td><td>POSIX <code>shm_open(2)</code> + <code>mmap(2)</code>. The one substitution. Same zero-IPC-read characteristic; portable across any Unix; matches Apple's user-visible semantic.</td></tr>
<tr><td>Subscriber wakeup (<code>NOTIFY_TYPE_PORT</code>)</td><td>Mach <code>mach_msg</code> to registered port</td><td>Identical. Native Mach mechanism on the v2 substrate.</td></tr>
<tr><td>Subscriber wakeup (<code>NOTIFY_TYPE_DISPATCH</code>)</td><td>Mach port message → libdispatch source</td><td>Identical. Subscriber holds a libdispatch <code>DISPATCH_SOURCE_TYPE_MACH_RECV</code> source; daemon sends a Mach message.</td></tr>
<tr><td>Path notifications</td><td>kqueue under the hood (already!)</td><td>kqueue. Identical.</td></tr>
<tr><td>Subscriber bookkeeping</td><td>Mach send-rights tracked per-client; subscriber-died detected via Mach port-no-senders notification</td><td>Both retained: Mach port-no-senders notification on the v2 substrate (the natural mechanism), augmented with <code>DISPATCH_SOURCE_TYPE_PROC</code> on each subscriber's PID as a belt-and-suspenders catch for clients that crash mid-message.</td></tr>
<tr><td>Build-system gates</td><td>iOS / sim / catalyst <code>#if</code></td><td>Delete. One target.</td></tr>
</tbody>
</table>
<h2 id="usecases">8. Use cases for gershwin</h2>
<p>What we get when notifyd lands and gershwin's apps can use it:</p>
<h3>8.1 Workspace (the desktop manager)</h3>
<table>
<thead><tr><th>Concern</th><th>Notification name</th><th>Effect</th></tr></thead>
<tbody>
<tr><td>Theme / appearance change</td><td><code>org.freebsd.appearance.theme-changed</code></td><td>Appearance prefs panel writes the new theme; posts the name. Every running app subscribed re-themes instantly. No per-app D-Bus connection or polling.</td></tr>
<tr><td>Application activation / focus</td><td><code>org.freebsd.workspace.app-activated</code></td><td>Other apps de-emphasize selves (dim accent colors, pause animations).</td></tr>
<tr><td>Hide / show all (NeXTSTEP signature)</td><td><code>org.freebsd.workspace.hide-others</code></td><td>Workspace single-post; all subscribed apps minimize.</td></tr>
<tr><td>Display configuration changed</td><td><code>org.freebsd.display.changed</code></td><td>configd or kmodloader detects framebuffer plug; posts. Workspace reflows windows; full-screen video apps react.</td></tr>
<tr><td>Login / logout</td><td><code>org.freebsd.session.user-logged-in</code> / <code>...logged-out</code></td><td>Per-user launchd agents (mail-checker, dock helpers, calendar-sync) wake. Mirrors Apple's <code>loginwindow</code> flow.</td></tr>
</tbody>
</table>
<h3>8.2 System-state fanout</h3>
<table>
<thead><tr><th>Concern</th><th>Notification name</th><th>Effect</th></tr></thead>
<tbody>
<tr><td>Battery / power</td><td><code>org.freebsd.power.battery-changed</code></td><td>One <code>powermon</code> daemon (or extension to configd's <code>KernelEventMonitor</code>) reads ACPI; posts current state. Workspace menubar battery icon, lid-close handler, screen-dim policy all subscribe. <strong>One source, many subscribers</strong> — without notifyd, every consumer would need its own ACPI listener.</td></tr>
<tr><td>Network state</td><td><code>org.freebsd.config.network-reachable</code></td><td>configd posts when an interface becomes reachable. Mail, browsers, sync clients subscribe. Apps check on each post — no polling, no per-app socket to configd.</td></tr>
<tr><td>Sleep / wake</td><td><code>org.freebsd.power.sleep-requested</code> + <code>...wake</code></td><td>Apps save state, pause downloads, dim UI before sleep; resume after wake.</td></tr>
<tr><td>Time / TZ change</td><td><code>org.freebsd.time.timezone-changed</code></td><td>Calendar, Mail, Clock all subscribe. Currently apps poll or recompute on every operation.</td></tr>
<tr><td>Filesystem mount / unmount</td><td><code>org.freebsd.fs.mounted</code> / <code>...unmounted</code></td><td>Workspace's File Viewer (Finder-equivalent) updates the sidebar. ZFS pool import — mount-aware apps refresh.</td></tr>
<tr><td>Keyboard layout change</td><td><code>org.freebsd.input.layout-changed</code></td><td>Apps refresh shortcut displays.</td></tr>
<tr><td>Audio volume / mute</td><td><code>org.freebsd.audio.volume-changed</code></td><td>Sound prefs slider follows hardware media keys; menubar volume icon updates.</td></tr>
</tbody>
</table>
<h3>8.3 Defaults / preferences plumbing</h3>
<p>This is where notifyd shines compared to alternatives. <code>NSUserDefaults</code> cross-app coordination on macOS is a notifyd story:</p>
<ol>
<li>App A calls <code>[defaults setObject:newValue forKey:@"FontFamily"]</code></li>
<li><code>cfprefsd</code>-equivalent (the prefs daemon) writes the file, posts <code>org.freebsd.prefs.<domain>.changed</code></li>
<li>App B (subscribed) gets woken, reloads the relevant key</li>
<li>App B's UI updates without a restart</li>
</ol>
<p>Without notifyd, every app would either poll the prefs file or rely on filesystem-watching primitives like <code>kqueue(EVFILT_VNODE)</code> — clunky compared to a single named post. <strong>gershwin's <code>NSUserDefaults</code> gets a noticeable UX upgrade</strong> when this works correctly across processes.</p>
<h3>8.4 launchd-event-driven service activation</h3>
<p>Apple uses notifyd to <strong>trigger launchd jobs</strong> without explicit RPC:</p>
<pre class="plist"><code><key>LaunchEvents</key>
<dict>
<key>com.apple.notifyd.matching</key>
<dict>
<key>org.freebsd.network-reachable</key>
<dict/>
</dict>
</dict></code></pre>
<p>A daemon plist with this <code>LaunchEvents</code> stanza launches its program <em>only when</em> that named notification posts. Auto-update checker idle until network up; backup daemon idle until specific conditions; etc. <strong>Replaces both "phase markers" (the proposed <code>RequiresPhase</code> per launchd plan §11.3) and ad-hoc polling with one unified mechanism.</strong> Adding <code>LaunchEvents</code> support to launchd alongside this notifyd port unlocks an Apple-native event-driven supervision model.</p>
<h3>8.5 Third-party Apple-derived apps "just work"</h3>
<p>Practical concrete: any app you'd port from macOS that calls <code>notify_register_dispatch()</code> or <code>notify_post()</code> works without modification. Without notifyd we'd either need to:</p>
<ul>
<li>Stub out libnotify (apps silently never get notified — broken)</li>
<li>Reroute libnotify calls to a different mechanism per-app (porting tax that scales with app count)</li>
</ul>
<p>With notifyd present, the calls Just Work.</p>
<h2 id="integration">9. launchd integration</h2>
<h3>9.1 The plist</h3>
<pre class="plist"><code><?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
<key>Label</key> <string>com.apple.notifyd</string>
<key>ProgramArguments</key> <array><string>/usr/libexec/notifyd</string></array>
<key>RunAtLoad</key> <true/>
<key>KeepAlive</key> <true/>
<key>MachServices</key> <dict>
<key>com.apple.notifyd</key> <true/>
<key>com.apple.system.notification_center</key> <true/>
</dict>
</dict>
</plist></code></pre>
<p>launchd registers the Mach service names on notifyd's behalf; clients <code>bootstrap_look_up</code> them and obtain a send right; notifyd calls <code>bootstrap_check_in</code> at startup to receive the receive right. Pending client messages queue on the port even when notifyd is restarting.</p>
<h3>9.2 Boot ordering</h3>
<p>notifyd has no dependencies on other daemons — it's a leaf service. ASL's libsystem_asl uses notifyd internally for fan-out (every log write posts <code>com.apple.system.logger</code>); configd, PowerManagement, IPConfiguration, DiskArbitration, IOKitUser all post / register for named events. Order it alongside other system daemons; no explicit ordering needed (launchd's bootstrap machinery handles "client looks up service before service has checked in" via held messages).</p>
<h2 id="license">10. Licensing</h2>
<p>Apple's Libnotify source is <strong>APSL</strong> (1.1 in older files, 2.0 in newer; preserve whichever each file carries). Same family of license as ASL; FSF-approved free software; not GPL-compatible (irrelevant for our project — no GPL deps).</p>
<table>
<thead><tr><th>Source</th><th>License</th><th>How we handle it</th></tr></thead>
<tbody>
<tr><td>Apple Libnotify-98.5 (per-file APSL headers)</td><td>APSL 1.1 / 2.0 mix</td><td>Keep per-file headers verbatim. Our edits inherit APSL via inbound=outbound — those individual files stay APSL regardless of top-level repo license.</td></tr>
<tr><td>This repo's new code (FreeBSD shims, build glue, shm-replacement of vm_allocate)</td><td>BSD-2-Clause</td><td>SPDX header on each new file.</td></tr>
<tr><td>libdispatch, libxpc, libCoreFoundation (in-tree, in <code>src/</code>)</td><td>Apache 2.0 / APSL</td><td>Listed in <code>NOTICE</code>. Same calculus as launchd/configd/ASL.</td></tr>
</tbody>
</table>
<h2 id="phases">11. Phased delivery</h2>
<p>On the v2 (Mach-IPC) track notifyd ships as part of the ASL block — see the <a href="freebsd-asl-plan.html">ASL plan</a>'s Phase J1/J2 for the joint build. Reproduced here for completeness:</p>
<div class="phase">
<h3>Phase J1 — <code>libnotify</code> <span class="pill ok">SHIPPED</span></h3>
<ul>
<li>Import Apple <code>Libnotify-98.5</code> into <code>src/Libnotify/</code>.</li>
<li>Build <code>libnotify.so</code>: client API library. MIG client stubs generated from <code>notify_ipc.defs</code> via FreeBSD's <code>mig(1)</code>. <code>notify_post</code>, <code>notify_register_dispatch</code>, <code>notify_register_signal</code>, <code>notify_register_file_descriptor</code>, <code>notify_register_mach_port</code>, <code>notify_cancel</code> all linkable; calls land on a Mach service name (no daemon yet — stubs return success).</li>
<li>Joint Phase J1 with ASL <code>libsystem_asl</code> because every <code>asl_*</code> log write posts <code>com.apple.system.logger</code> via libnotify.</li>
<li><strong>Wired into <code>build.sh</code></strong>; downstream linkers see <code>-lnotify</code>.</li>
</ul>
</div>
<div class="phase">
<h3>Phase J2 iter 1 — <code>notifyd</code> daemon <span class="pill ok">SHIPPED</span></h3>
<ul>
<li>Build <code>notifyd</code> from <code>src/Libnotify/notifyd/</code>. MIG server stubs generated from <code>notify_ipc.defs</code>.</li>
<li>Daemon registers Mach service <code>com.apple.notifyd</code> via <code>bootstrap_check_in</code>; receives requests via libdispatch <code>DISPATCH_SOURCE_TYPE_MACH_RECV</code> on the service port.</li>
<li>POSIX <code>shm_open</code> + <code>mmap</code> for state-value pages — atomic stores via <code><stdatomic.h></code>; clients map read-only at registration. The one substitution for Apple's <code>vm_allocate</code>+port-handoff.</li>
<li>All delivery types working: <code>NOTIFY_TYPE_PORT</code>, <code>NOTIFY_TYPE_DISPATCH</code>, <code>NOTIFY_TYPE_SIGNAL</code>, <code>NOTIFY_TYPE_FD</code>, <code>NOTIFY_TYPE_CHECK</code>.</li>
<li><code>com.apple.notifyd.plist</code> in <code>/System/Library/LaunchDaemons/</code>; launchd boot-starts it.</li>
</ul>
</div>
<div class="phase">
<h3>Phase J2 iter 2+ — pathwatch + notifyutil + launch-events <span class="pill warn">FOLLOW-UP</span></h3>
<ul>
<li>pathwatch.c (file-path-change notifications via kqueue) — Apple source is portable; thin wire-up.</li>
<li>notifyutil(1) CLI for admin/dev. Useful for boot-test verification.</li>
<li>launchd <code>LaunchEvents</code> + <code>com.apple.notifyd.matching</code> stanza support (notifyd-driven job-on-event activation). Replaces ad-hoc polling for "wait for network up", "wait for filesystems mounted", etc.</li>
</ul>
</div>
<div class="phase">
<h3>Phase K+ — downstream consumers <span class="pill warn">IN-FLIGHT</span></h3>
<ul>
<li>configd posts <code>com.apple.system.config.network_change</code> on reachability/store updates (consumed by Mail / browsers / sync clients).</li>
<li>PowerManagement, IPConfiguration, DiskArbitration, IOKitUser all link <code>-lnotify</code> and use the API natively (no porting work — Apple's code Just Works on the v2 Mach substrate).</li>
<li>gershwin Workspace, prefs panels, menubar widgets emit posts (theme, audio, network, battery, etc.) — landed alongside the gershwin desktop port.</li>
</ul>
</div>
<h2 id="open">12. Open questions</h2>
<div class="open-q">
<strong>Q1. Atomic uint64 across architectures.</strong> POSIX shm + atomic store works on amd64 native. arm64 + 32-bit hosts we'd want to verify torn-read semantics — <code>atomic_store_explicit(memory_order_relaxed)</code> is the right primitive but compiler / target-arch-specific. Phase 2 testing covers.
</div>
<div class="open-q">
<strong>Q2. Coexistence with NSDistributedNotificationCenter.</strong> GNUstep ships <code>NSDistributedNotificationCenter</code>, which is GNUstep's own pub/sub mechanism (separate from notifyd). Apps using <code>NSDistributedNotificationCenter</code> Just Work today. Apps using <code>notify_post</code> need our notifyd port. <strong>Both should coexist</strong> — they don't conflict; pick the API that matches the app's expectation. Long-term gershwin question: should new app code prefer one over the other? Decision deferrable.
</div>
<div class="open-q">
<strong>Q3. Naming convention for project-emitted events.</strong> Apple uses <code>com.apple.*</code> for system events. We propose <code>org.freebsd.*</code> for our project's posts (network, power, theme, etc.) and reserve <code>com.apple.*</code> for app-emitted compat names. <code>org.gershwin.*</code> for desktop-specific events. Keep these consistent across all FreeBSD-launchd-ecosystem code.
</div>
<div class="open-q">
<strong>Q4. Apple's <code>com.apple.system.config.network_change</code> compat.</strong> Apple-derived apps registering for that exact name will expect it to fire on network state change. Should configd post both the Apple-canon name and our <code>org.freebsd.config.network-changed</code>? Decision: yes, dual-post — costs nothing, retains source compat with apps that hard-coded the Apple name.
</div>
<div class="open-q">
<strong>Q5. State-page location and quotas.</strong> POSIX shm names default to <code>/dev/shm/</code> on Linux; FreeBSD uses <code>/tmp/...</code> or <code>swap/...</code> behind the scenes. Naming scheme: <code>org.freebsd.notifyd.state.<n></code> for daemon-managed segments. Per-host quota for state-value count: start at 16k slots; bump if real workloads need more.
</div>
<div class="open-q">
<strong>Q6. Bootstrapping order with launchd.</strong> notifyd needs to be running before <code>LaunchEvents</code>-using plists can be evaluated. If notifyd is itself launched by launchd, there's a chicken-and-egg if the launchd plist using <code>LaunchEvents</code> is loaded before notifyd is up. Decision: notifyd's own plist has highest priority RunAtLoad, no <code>LaunchEvents</code>; the launchd bootstrap machinery holds client <code>bootstrap_look_up("com.apple.notifyd")</code> calls until notifyd has called <code>bootstrap_check_in</code>. Same pattern as configd / WindowServer / any other Mach-service-providing daemon.
</div>
<div class="open-q">
<strong>Q7. Per-user notifyd vs single system-wide daemon.</strong> Apple runs one notifyd per session domain (system + each gui/<uid>). For our scope: start with system-wide only. Per-user notifyd waits until per-user launchd is implemented (post-Phase 6 of the launchd plan).
</div>
<h2 id="refs">13. References</h2>
<ul>
<li>Apple source: <a href="https://github.com/apple-oss-distributions/Libnotify">github.com/apple-oss-distributions/Libnotify</a> (latest tag <code>Libnotify-98.5</code>).</li>
<li>Companion plans: <a href="freebsd-launchd-plan.html">launchd</a>, <a href="nextbsd-configd-plan.html">configd</a>, <a href="freebsd-kmodloader-plan.html">kmodloader</a>, <a href="freebsd-asl-plan.html">asl</a>.</li>
<li>libnotify(3) API: <code>man 3 notify</code> on macOS, or <a href="https://developer.apple.com/library/archive/documentation/Darwin/Reference/ManPages/man3/notify.3.html">developer.apple.com/.../notify.3.html</a>.</li>
<li>Apple Public Source License: <a href="https://opensource.apple.com/apsl/">opensource.apple.com/apsl/</a>.</li>
<li>POSIX <code>shm_open(2)</code>: <code>man 2 shm_open</code>.</li>
</ul>
<hr>
<p class="footnote"><strong>Revision 2026-05-23.</strong> Refactored from the v1 (AF_UNIX / GNUstep DO) target to the v2 (<code>freebsd-launchd-mach</code> / Mach-IPC) target. notifyd <strong>SHIPPED</strong> in Phase J1 (<code>libnotify</code>) + Phase J2 iter 1 (<code>notifyd</code> daemon) under <code>src/Libnotify/</code>; MIG client/server stubs from <code>notify_ipc.defs</code>, libdispatch <code>DISPATCH_SOURCE_TYPE_MACH_RECV</code> on the service port, POSIX <code>shm_open</code>+<code>mmap</code> the sole substitution for Apple's <code>vm_allocate</code>+port-handoff. <code>NOTIFY_TYPE_PORT</code> retained (it was dropped in the v1 plan). Companion ASL plan at <a href="freebsd-asl-plan.html">freebsd-asl-plan.html</a>.</p>
</body>
</html>