The Local Namespace

This section describes the details of the local namespace, whose symbolic name (required when you create a socket) is PF_LOCAL. The local namespace is also known as "Unix domain sockets". Another name is file namespace since socket addresses are normally implemented as file names.

Local Namespace Concepts

In the local namespace socket addresses are file names. You can specify any file name you want as the address of the socket, but you must have write permission on the directory containing it. It's common to put these files in the /tmp directory.

One peculiarity of the local namespace is that the name is only used when opening the connection; once open the address is not meaningful and may not exist.

Another peculiarity is that you cannot connect to such a socket from another machine-not even if the other machine shares the file system which contains the name of the socket. You can see the socket in a directory listing, but connecting to it never succeeds. Some programs take advantage of this, such as by asking the client to send its own process ID, and using the process IDs to distinguish between clients. However, we recommend you not use this method in protocols you design, as we might someday permit connections from other machines that mount the same file systems. Instead, send each new client an identifying number if you want it to have one.

After you close a socket in the local namespace, you should delete the file name from the file system. Use unlink or remove to do this; see the section called “Deleting Files”.

The local namespace supports just one protocol for any communication style; it is protocol number 0.

Details of Local Namespace

To create a socket in the local namespace, use the constant PF_LOCAL as the namespace argument to socket or socketpair. This constant is defined in sys/socket.h.

int function>PF_LOCAL/function> This designates the local namespace, in which socket addresses are local names, and its associated family of protocols. PF_Local is the macro used by Posix.1g.

int function>PF_UNIX/function> This is a synonym for PF_LOCAL, for compatibility's sake.

int function>PF_FILE/function> This is a synonym for PF_LOCAL, for compatibility's sake.

The structure for specifying socket names in the local namespace is defined in the header file sys/un.h: function>struct sockaddr_un/function> This structure is used to specify local namespace socket addresses. It has the following members:

short int sun_family

This identifies the address family or format of the socket address. You should store the value AF_LOCAL to designate the local namespace. the section called “Socket Addresses”.

char sun_path[108]

This is the file name to use.

Incomplete: Why is 108 a magic number? RMS suggests making this a zero-length array and tweaking the following example to use alloca to allocate an appropriate amount of storage based on the length of the filename.

You should compute the length parameter for a socket address in the local namespace as the sum of the size of the sun_family component and the string length (not the allocation size!) of the file name string. This can be done using the macro SUN_LEN:

int function>SUN_LEN/function> (struct sockaddr_un *ptr) The macro computes the length of socket address in the local namespace.

Example of Local-Namespace Sockets

Here is an example showing how to create and name a socket in the local namespace.

#include stddef.h
#include stdio.h
#include errno.h
#include stdlib.h
#include sys/socket.h
#include sys/un.h

int
make_named_socket (const char *filename)
{
  struct sockaddr_un name;
  int sock;
  size_t size;

  /* Create the socket. */
  sock = socket (PF_LOCAL, SOCK_DGRAM, 0);
  if (sock  0)
    {
      perror ("socket");
      exit (EXIT_FAILURE);
    }

  /* Bind a name to the socket. */
  name.sun_family = AF_LOCAL;
  strncpy (name.sun_path, filename, sizeof (name.sun_path));

  /* The size of the address is
     the offset of the start of the filename,
     plus its length,
     plus one for the terminating null byte.
     Alternatively you can just do:
     size = SUN_LEN (name);
 */
  size = (offsetof (struct sockaddr_un, sun_path)
          + strlen (name.sun_path) + 1);

  if (bind (sock, (struct sockaddr *) name, size)  0)
    {
      perror ("bind");
      exit (EXIT_FAILURE);
    }

  return sock;
}