Bug 227777 - Missing a manual page for socket control message routines (ancillary data) like CMSG_DATA
Summary: Missing a manual page for socket control message routines (ancillary data) li...
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Some People
Assignee: freebsd-doc (Nobody)
URL:
Keywords: needs-qa, patch
Depends on:
Blocks:
 
Reported: 2018-04-25 20:35 UTC by Mateusz Piotrowski
Modified: 2018-08-19 17:43 UTC (History)
2 users (show)

See Also:

Attachments
Patch adding a CMSG_DATA.3 manual page (6.91 KB, patch)
2018-04-26 02:12 UTC, Mateusz Piotrowski 		no flags Details | Diff
Patch adding a CMSG_DATA.3 manual page (revision: 1) (8.18 KB, patch)
2018-04-27 14:47 UTC, Mateusz Piotrowski 		no flags Details | Diff
Show Obsolete (2) View All Add an attachment (proposed patch, testcase, etc.)

Note You need to log in before you can comment on or make changes to this bug.
Description Mateusz Piotrowski freebsd_committer freebsd_triage 2018-04-25 20:35:06 UTC 
It looks like FreeBSD is missing a manual page for macros defined in sys/sys/socket.h[1]. The man page is present for example in Linux as cmsg(3)[2] and in OpenBSD as CMSG_DATA[3].


[1]: https://github.com/freebsd/freebsd/blob/master/sys/sys/socket.h#L532
[2]: http://man7.org/linux/man-pages/man3/cmsg.3.html
[3]: https://man.openbsd.org/CMSG_DATA.3
Comment 1 Mateusz Piotrowski freebsd_committer freebsd_triage 2018-04-25 20:41:07 UTC 
There's also a nice blog post[1] about FreeBSD SCTP ancillary data by Tsvetomir Dimitrov. 

[1]: http://petanode.com/blog/posts/sctp-freebsd-ancillary-data.html
Comment 2 Mateusz Piotrowski freebsd_committer freebsd_triage 2018-04-26 02:12:50 UTC 
Created attachment 192820 [details]
Patch adding a CMSG_DATA.3 manual page

Here's a manual page for CMSG_DATA based on an OpenBSD one. It looks like it does not need much tweaking as the presented information are true on FreeBSD as well. I've added cross references to related manpages and RFCs.

I am not sure about the example though. It does not define all the required variables. I may try to make more descriptive and complete.
Comment 3 Mateusz Piotrowski freebsd_committer freebsd_triage 2018-04-27 14:47:55 UTC 
Created attachment 192846 [details]
Patch adding a CMSG_DATA.3 manual page (revision: 1)

Changes:

 - Add CMSG_DATA.3 to Makefile.
 - Update example:
  - Consolidate examples into one working, compile-and-run example.
  - Remove an unneeded iovec structure. Nothing is sent using msg_iov buffers so there's it's a good idea to remove them completely. It makes the example less confusing.
Comment 4 Mateusz Piotrowski freebsd_committer freebsd_triage 2018-04-27 15:14:42 UTC 
Code review: https://reviews.freebsd.org/D15215
Comment 5 commit-hook freebsd_committer freebsd_triage 2018-08-19 17:42:57 UTC 
A commit references this bug:

Author: 0mp
Date: Sun Aug 19 17:42:51 UTC 2018
New revision: 338060
URL: https://svnweb.freebsd.org/changeset/base/338060

Log:
  Document socket control message routines for ancillary data access (CMSG_DATA).

  PR:		227777
  Reviewed by:	bcr, eadler
  Approved by:	mat (mentor), manpages (bcr)
  Obtained from:	OpenBSD
  Differential Revision:	https://reviews.freebsd.org/D15215

Changes:
  head/lib/libc/sys/recv.2
  head/lib/libc/sys/send.2
  head/lib/libc/sys/socket.2
  head/share/man/man3/CMSG_DATA.3
  head/share/man/man3/Makefile
  head/share/man/man4/ip.4
  head/share/man/man4/ip6.4
  head/share/man/man4/unix.4