From a66f1e2e51d571663bfef779ce0f4d4f90964352 Mon Sep 17 00:00:00 2001 From: Christian Ulrich Date: Wed, 21 Oct 2020 00:50:34 +0200 Subject: [PATCH] clarify 'Receiving sockets' section --- README.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index f6ebe3a..35e3266 100644 --- a/README.md +++ b/README.md @@ -116,20 +116,23 @@ AA <- PA: ok|645 ``` -## Receiving sockets using recvmsg +## Receiving sockets using sendmsg/recvmsg When ``punchd`` successfully has punched a hole, i.e. has a socket that is connected to the other peer, it will report back status "ok" to the application. -The file descriptor representing that socket will be included in the status -message in a control message, a.k.a ancillary message. +But how can the application now use the socket? The answer is: ``punchd`` has to +pass the corresponding file descriptor to the application's process. On Unix +systems that is possible using the system calls ``sendmsg`` (on ``punchd``'s +side) and ``recvmsg`` (on the application's side). This allows ``punchd`` +passing a control message, a.k.a. ancillary message, of type ``SCM_RIGHTS`` +along with the actual contents of the status message. This control message will +contain the file descriptor. -The application has to use the ``recvmsg`` system call to receive that control -message (it has the type ``SCM_RIGHTS``) and access the file descriptor. This -mechanism is described in the man pages -[unix(7)](https://linux.die.net/man/7/unix), +The mechanism of passing file descriptors to other processes is described in the +man pages [unix(7)](https://linux.die.net/man/7/unix), [cmsg(3)](https://linux.die.net/man/3/cmsg) and [recv(2)](https://linux.die.net/man/2/recv). The example applications can be used -as a reference too. After receiving the file descriptor it can immediately be -used to send data to the other peer. +as a reference too. After receiving the file descriptor the application can +immediately use it to send data to the other peer. # FAQ