API tools faq
paste
Guest User

illumos man page bugs

a guest
Dec 2nd, 2025
44
0
19 days
Add comment
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
text 17.51 KB | Software | 0 0
raw download clone embed print report
  1. Our man page changes for this quarter are at:
  2. https://gist.github.com/alanc/412842f5e4cc6b0f67acfb92d16c7b00
  3.  
  4. Along with a cleanup pass of extra space inserted by our XML->nroff conversions,
  5. my big man page project for the quarter was a cleanup pass across the
  6. section 3C man pages. Changes from those included:
  7.  
  8. - Formatting, spelling, grammar, wording, and typo fixes across many pages
  9. - Remove less useful / add more useful "See Also" entries in several pages
  10. - Add History sections to many pages
  11. - Add Attributes tables in a few pages
  12. - Standardize on <> being included in the bold text for header references
  13. (by standardizing on <filename class="headerfile"> markup in the XML)
  14. - Note that thread-specific data returned by some functions will
  15. be unallocated when the thread is gone.
  16.  
  17. clock(3C):
  18. - Update usage note to reflect that clock_t is a typedef long, so only
  19. overflows quickly in 32-bit processes, not 64-bit.
  20.  
  21. clock_settime(3C):
  22. - Add missing CLOCK_MONOTONIC definition (specified by POSIX).
  23.  
  24. ctime(3C):
  25. - Stop claiming the sysadmin has to set DST switching dates every year
  26. since we now rely on the timezone database for that.
  27.  
  28. dup3(3C):
  29. - Reflect clarification from https://austingroupbugs.net/view.php?id=1577
  30.  
  31. getopt(3C);
  32. - Show 21st century standards first, ahead of 20th century standards.
  33.  
  34. getrusage(3C):
  35. - Stop insulting raf's memory and correct the claim that it is impossible
  36. to get resource usage information of processes that have not yet
  37. terminated when /proc is right there.
  38. - Replace sar(8) with sstore(1).
  39.  
  40. getsubopt(3C):
  41. - Restore introductory text from SunOS 4 man page that explains what
  42. suboptions are.
  43.  
  44. getvfsent(3C):
  45. - Add USAGE section suggesting you probably want getmntent(3C) instead.
  46.  
  47. posix_fallocate(3C):
  48. - Add note to USAGE section warning that it does not work on ZFS.
  49.  
  50. posix_spawnattr_destroy(3C):
  51. - Correct claim that Solaris has no attributes not defined by POSIX,
  52. since while that was true for Solaris 10, it's not been true since 11.0.
  53.  
  54. select(3C):
  55. - Correct info on default open file limit.
  56.  
  57. setjmp(3C):
  58. - Clarify that these functions operate on a single thread.
  59.  
  60. shutdown(3C):
  61. - Clarify that shutdown() doesn't close the socket, the caller has to.
  62.  
  63. Fixes I see that apply to your pages as well include:
  64.  
  65. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man2/msgrcv.2#L252
  66. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man2/msgsnd.2#L231
  67. - Extra space between "\fB" and "\fB"
  68.  
  69. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3/Intro.3#L959
  70. - NULL is defined in <stddef.h>, not <stdio.h>
  71. - many more definitions are provided in Intro(2)
  72.  
  73. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3/Intro.3#L1106
  74. - missing <> around math.h
  75.  
  76. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/abort.3c#L21
  77. - "is being caught" should be "is caught", per
  78. https://austingroupbugs.net/view.php?id=906
  79.  
  80. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/abort.3c#L46
  81. - if coreadm is configured to capture global core dumps, or core dumps under
  82. a different path, a core dump may be produced even if the current directory
  83. is not writable
  84.  
  85. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/attropen.3c#L17
  86. - the opening "/*" and closing "*/" are mismatched levels of boldness
  87.  
  88. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/clock.3c#L37-L38
  89. - the 36 minute wraparound claim is only true in 32-bit code (but we still
  90. added a recommendation to use clock_gettime(3C) with CLOCK_PROCESS_CPUTIME_ID
  91. instead of this function)
  92.  
  93. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/cond_init.3c#L430
  94. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getopt.3c#L421
  95. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3scf/scf_transaction_create.3scf#L551
  96. - extra space before comma
  97.  
  98.  
  99. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/ctime.3c#L210-L213
  100. - libc also knows about the 2007 changes to US daylight savings time, in which
  101. daylight savings time now starts in March, not on the first Sunday in April.
  102.  
  103. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/ctime.3c#L394-L395
  104. - sysadmins are no longer required to do this as long as tzdata is up to date
  105.  
  106. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/dlinfo.3c#L280
  107. - "one of more" should be "one or more"
  108.  
  109. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/door_create.3c
  110. - missing a mention of the new & improved door_xcreate(3C) alternative API
  111. (for which you seem to be missing the man page entirely - see
  112. https://illumos.org/opensolaris/ARChive/PSARC/2009/554/index.html )
  113.  
  114. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/door_getparam.3c#L171
  115. - missing "the" before "supported range"
  116.  
  117. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/door_getparam.3c#L182
  118. - missing "ch" and indentation for "char" variable type
  119.  
  120. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/dup2.3c#L101
  121. - this can also happen for dup3() not just dup2()
  122.  
  123. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/freopen.3c#L53
  124. - the arguments should have the "restrict" qualifier to match the header
  125.  
  126. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/ftell.3c#L82
  127. - "sets" should be "set", since the subject is "they"
  128.  
  129. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getgrnam.3c#L240-L241
  130. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getlogin.3c#L187-L188
  131. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getpwnam.3c#L268-L269
  132. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getspnam.3c#L172-L173
  133. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/ptsname.3c#L125-L127
  134. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/ttyname.3c#L170-L171
  135. - use of thread-specific data must also not be done after the thread which
  136. made the call has ended (see https://austingroupbugs.net/view.php?id=656
  137. for these & more)
  138.  
  139. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/gethrtime.3c#L38
  140. - comma should not be inside the bold markup
  141.  
  142. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/gethrtime.3c
  143. - does not mention that clock_gettime(3C) is the standard/portable API for this
  144. functionality now
  145.  
  146. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getopt.3c#L93
  147. - Intro(1) should be marked up as a man page reference
  148.  
  149. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getopt.3c#L455
  150. - This sentence has very twisted up grammar.
  151.  
  152. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getrusage.3c#L331-L332
  153. - This limitation is only true for this API - the use of proc(5) allows
  154. gathering information about running processes.
  155.  
  156. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getspnam.3c#L121
  157. - The "." should not be inside the italic markup.
  158.  
  159. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getspnam.3c#L160
  160. - Missing space before "and"
  161.  
  162. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getspnam.3c#L214-L218
  163. - This warning seems unnecessary now and can be replaced by a Stability level
  164. in the Attributes table. (They've been there since Solaris 2.3.)
  165.  
  166. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getsubopt.3c
  167. - it helps to explain that "suboption arguments" are comma separated arguments,
  168. like the mount command uses for the -o option.
  169.  
  170. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getsubopt.3c#L138-L140
  171. - K&R C is so pre-1989 (and the rest of the code could use some cstyle help)
  172.  
  173. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getutxent.3c#L165
  174. - "." or ";" pick one, but don't put both together
  175.  
  176. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getutxent.3c#L173
  177. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getutxent.3c#L178
  178. - missing "the" after "for"
  179.  
  180. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getutxent.3c#L188
  181. - missing ")" to match "(" two lines above it.
  182.  
  183. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getutxent.3c#L204
  184. - unnecessary "," after "wait(3C)"
  185.  
  186. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getutxent.3c#L242
  187. - extra space between "getutxid" and "()"
  188.  
  189. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getutxent.3c#L312
  190. - missing "utmpd(8)" in See Also list
  191.  
  192. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/getvfsent.3c#L62
  193. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/ndbm.3c#L107
  194. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/ndbm.3c#L107
  195. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/ndbm.3c#L331
  196. - "file" should be italic (argument name) not bold (command/function name)
  197.  
  198. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/glob.3c
  199. - the markup including "->" in the italic section with "pglob" in many places
  200. in this page looks funny
  201.  
  202. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/isastream.3c#L22
  203. - "return" should be "returned"
  204.  
  205. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/madvise.3c
  206. - no mentions or even see also for madv.so.1(1), pmadvise(1), posix_madvise(3C)
  207.  
  208. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/mutex_init.3c#L582-L583
  209. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/mutex_init.3c#L649-L650
  210. - it's not necessary to set i=0 in both lines (and this code could also use
  211. some cstyle help, and a return type for main() now that compilers reject
  212. implicit int declarations)
  213.  
  214. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/ndbm.3c#L193
  215. - extra space before "."
  216.  
  217. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/ndbm.3c#L311-L313
  218. - Copies can be made without filling the holes by using cpio, pax, or GNU cp now.
  219.  
  220. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/popen.3c#L178
  221. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/setjmp.3c#L166
  222. - main() should have a return type and argument information to make ANSI C
  223. compilers happy
  224.  
  225. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/port_get.3c#L94
  226. - "errno" should be bold
  227.  
  228. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/posix_fallocate.3c
  229. - doesn't warn that this function doesn't actually allocate space on ZFS
  230.  
  231. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/posix_spawnattr_destroy.3c#L85
  232. - at least for us, it's no longer true that no non-standard attributes are
  233. provided by the OS
  234.  
  235. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/posix_spawnattr_getflags.3c#L122-L123
  236. - missing markup for parameter/variable names
  237.  
  238. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/realpath.3c
  239. - does not mention that if you pass NULL for resolved_name, you are responsible
  240. for freeing the newly allocated buffer (yours doesn't even seem to mention
  241. this is allowed, except that canonicalize_file_path says it does that,
  242. even though ERRORS says it will return EINVAL for that)
  243. - does not mention that if you pass a buffer for resolved_name, it must be
  244. at least PATH_MAX bytes.
  245.  
  246. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/setjmp.3c#L84-L88
  247. - sigsetjmp() saves registers/stack/signal mask for just the calling thread,
  248. not every thread in the process
  249.  
  250. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/setjmp.3c#L260-L262
  251. - Warnings missing note from
  252. https://pubs.opengroup.org/onlinepubs/9699919799/functions/longjmp.html
  253. that calling *longjmp from a different thread than *setjmp is undefined.
  254.  
  255. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3socket/shutdown.3socket
  256. - Does not say that the caller is responsible for calling close() after
  257. shutdown() completes.
  258.  
  259. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/signal.3c#L108
  260. - missing "of" after "execution"
  261.  
  262. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/ungetc.3c#L24-L25
  263. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man9e/devmap.9e#L128-L129
  264. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man9e/ioctl.9e#L172-L174
  265. - newline after "(" causes extra space in output
  266.  
  267. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/wait.3c#L62-L65
  268. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/wait3.3c#L24-L25
  269. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/waitpid.3c#L62-L65
  270. - missing case for immediate return (no waiting) on error - see
  271. https://austingroupbugs.net/view.php?id=690
  272.  
  273. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/wait.3c#L94
  274. - missing space between "7" and "bits"
  275.  
  276. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/wait3.3c#L108
  277. - "return" should be "returns"
  278.  
  279. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/wait3.3c#L191
  280. - missing space between "wait3()\fR" and "and"
  281.  
  282. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/waitpid.3c#L213
  283. - the "." should not be inside the italic markup
  284.  
  285. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/wordexp.3c
  286. - the markup including "->" in the italic section with "exp" in many places
  287. in this page looks funny
  288.  
  289. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3c/wordexp.3c#L367
  290. - "executing shell command" should be either "a shell command" or
  291. "shell commands"
  292.  
  293. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3curses/curs_addwchstr.3curses#L51
  294. - "chtype" should be bold, "wchstr" should be italic
  295.  
  296. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man2/msgsnd.2#L278
  297. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3curses/curs_getch.3curses#L109
  298. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3curses/curs_getwch.3curses#L110
  299. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3curses/curs_touch.3curses#L61
  300. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3curses/menu_opts.3curses#L118
  301. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3xcurses/getch.3xcurses#L149
  302. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3xcurses/keypad.3xcurses#L133
  303. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3xcurses/keypad.3xcurses#L135
  304. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3xcurses/keypad.3xcurses#L141
  305. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3xcurses/keypad.3xcurses#L180
  306. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3xcurses/vwscanw.3xcurses#L30
  307. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man4d/qlc.4d#L124
  308. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man9f/STRUCT_DECL.9f#L101
  309. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man9f/ddi_get_devstate.9f#L50
  310. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man9f/ddi_get_devstate.9f#L59
  311. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man9f/ddi_get_devstate.9f#L70
  312. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man9f/ddi_get_devstate.9f#L80
  313. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man9f/ddi_get_pid.9f#L31
  314. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man9f/ddi_get_pid.9f#L39
  315. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man9f/ddi_get_time.9f#L33
  316. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man9f/ddi_get_time.9f#L44
  317. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man9f/usb_pipe_isoc_xfer.9f#L164
  318. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man9f/usb_pipe_isoc_xfer.9f#L297
  319. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man9s/scsi_asc_key_strings.9s#L15
  320. - Extra space at start of line
  321.  
  322. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3curses/curs_getwch.3curses#L49-L50
  323. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3curses/curs_inopts.3curses#L165
  324. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3xcurses/get_wch.3xcurses#L67
  325. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man9e/devmap.9e#L130
  326. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man9f/getq.9f#L37
  327. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man9f/mt-streams.9f#L31
  328. - Extra spaces after "(" and/or before ")"
  329.  
  330. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man3xcurses/immedok.3xcurses#L29
  331. - Extra space before "()"
  332.  
  333. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man4d/ibcm.4d
  334. - Extra space before "Consolidation Private"
  335.  
  336. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man4d/qlc.4d#L105
  337. https://github.com/illumos/illumos-gate/blob/master/usr/src/man/man4d/qlc.4d#L111
  338. - Extra spaces between words in titles
  339.  
Advertisement
Add Comment
Please, Sign In to add comment
Public Pastes
We use cookies for various purposes including analytics. By continuing to use Pastebin, you agree to our use of cookies as described in the Cookies Policy.  OK, I Understand
Not a member of Pastebin yet?
Sign Up, it unlocks many cool features!