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