chiark / gitweb /
File descriptor passing.
authormdw <mdw>
Sat, 29 Nov 2003 11:58:49 +0000 (11:58 +0000)
committermdw <mdw>
Sat, 29 Nov 2003 11:58:49 +0000 (11:58 +0000)
fdpass.c [new file with mode: 0644]
fdpass.h [new file with mode: 0644]
man/fdpass.3 [new file with mode: 0644]

diff --git a/fdpass.c b/fdpass.c
new file mode 100644 (file)
index 0000000..95685e7
--- /dev/null
+++ b/fdpass.c
@@ -0,0 +1,162 @@
+/* -*-c-*-
+ *
+ * $Id: fdpass.c,v 1.1 2003/11/29 11:58:49 mdw Exp $
+ *
+ * File descriptor passing
+ *
+ * (c) 2003 Straylight/Edgeware
+ */
+
+/*----- Licensing notice --------------------------------------------------* 
+ *
+ * This file is part of the mLib utilities library.
+ *
+ * mLib is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Library General Public License as
+ * published by the Free Software Foundation; either version 2 of the
+ * License, or (at your option) any later version.
+ * 
+ * mLib is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Library General Public License for more details.
+ * 
+ * You should have received a copy of the GNU Library General Public
+ * License along with mLib; if not, write to the Free
+ * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
+ * MA 02111-1307, USA.
+ */
+
+/*----- Revision history --------------------------------------------------* 
+ *
+ * $Log: fdpass.c,v $
+ * Revision 1.1  2003/11/29 11:58:49  mdw
+ * File descriptor passing.
+ *
+ */
+
+/*----- Header files ------------------------------------------------------*/
+
+#include <errno.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include <sys/types.h>
+#include <sys/time.h>
+#include <unistd.h>
+#include <sys/socket.h>
+#include <sys/uio.h>
+#include <sys/un.h>
+
+#include "fdpass.h"
+
+/*----- Main code ---------------------------------------------------------*/
+
+/* --- @fdpass_send@ --- *
+ *
+ * Arguments:  @int sock@ = socket to send over
+ *             @int fd@ = file descriptor to send
+ *             @const void *p@ = pointer to data to send
+ *             @size_t sz@ = size of buffer to send
+ *
+ * Returns:    On error, @-1@, otherwise number of bytes transferred from
+ *             @p@.
+ *
+ * Use:                Sends a copy of file descriptor @fd@ to the other end of
+ *             @sock@.
+ */
+
+ssize_t fdpass_send(int sock, int fd, const void *p, size_t sz)
+{
+  struct iovec iov;
+  struct msghdr msg;
+#ifndef HAVE_MSG_ACCRIGHTS
+  char buf[CMSG_SPACE(sizeof(fd))];
+  struct cmsghdr *cmsg;
+#endif
+
+  iov.iov_base = (/*unconst*/ void *)p;
+  iov.iov_len = sz;
+  msg.msg_name = 0;
+  msg.msg_namelen = 0;
+  msg.msg_iov = &iov;
+  msg.msg_iovlen = 1;
+  msg.msg_flags = 0;
+#ifdef HAVE_MSG_ACCRIGHTS
+  msg.msg_accrights = &fd;
+  msg.msg_accrightslen = sizeof(fd);
+#else  
+  msg.msg_control = buf;
+  msg.msg_controllen = sizeof(buf);
+  cmsg = CMSG_FIRSTHDR(&msg);
+  cmsg->cmsg_len = CMSG_LEN(sizeof(fd));
+  cmsg->cmsg_level = SOL_SOCKET;
+  cmsg->cmsg_type = SCM_RIGHTS;
+  memcpy(CMSG_DATA(cmsg), &fd, sizeof(fd));
+#endif
+  return (sendmsg(sock, &msg, 0));
+}
+
+/* --- @fdpass_recv@ --- *
+ *
+ * Arguments:  @int sock@ = socket to send over
+ *             @int *fd@ = where to put received descriptor
+ *             @void *p@ = pointer to where to put data
+ *             @size_t sz@ = size of buffer
+ *
+ * Returns:    On error, @-1@, otherwise number of bytes transferred.
+ *
+ * Use:                Receives a file descriptor.  If the call succeeds, and there
+ *             was a file descriptor, then @fd@ won't be @-1@ on exit;
+ *             otherwise it will.  At most one descriptor will be collected.
+ */
+
+ssize_t fdpass_recv(int sock, int *fd, void *p, size_t sz)
+{
+  struct iovec iov;
+  struct msghdr msg;
+  ssize_t rc;
+#ifndef HAVE_MSG_ACCRIGHTS
+  char buf[CMSG_SPACE(sizeof(fd))];
+  struct cmsghdr *cmsg;
+  int fdtmp;
+#endif
+
+  *fd = -1;
+  iov.iov_base = p;
+  iov.iov_len = sz;
+  msg.msg_name = 0;
+  msg.msg_namelen = 0;
+  msg.msg_iov = &iov;
+  msg.msg_iovlen = 1;
+  msg.msg_flags = 0;
+#ifdef HAVE_MSG_ACCRIGHTS
+  msg.msg_accrights = fd;
+  msg.msg_accrightslen = sizeof(*fd);
+#else
+  msg.msg_control = buf;
+  msg.msg_controllen = sizeof(buf);
+#endif
+  if ((rc = recvmsg(sock, &msg, 0)) < 0)
+    return (rc);
+#ifdef HAVE_MSG_ACCRIGHTS
+  if (msg.msg_accrightslen < sizeof(*fd))
+    *fd = -1;
+#else
+  for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) {
+    if (cmsg->cmsg_level == SOL_SOCKET &&
+       cmsg->cmsg_type == SCM_RIGHTS &&
+        cmsg->cmsg_len >= CMSG_LEN(sizeof(fd))) {
+      memcpy(&fdtmp, CMSG_DATA(cmsg), sizeof(fdtmp));
+      if (*fd == -1)
+       *fd = fdtmp;
+      else
+       close(fdtmp);
+    }
+  }
+#endif
+  return (rc);
+}
+
+/*----- That's all, folks -------------------------------------------------*/
diff --git a/fdpass.h b/fdpass.h
new file mode 100644 (file)
index 0000000..0e14078
--- /dev/null
+++ b/fdpass.h
@@ -0,0 +1,92 @@
+/* -*-c-*-
+ *
+ * $Id: fdpass.h,v 1.1 2003/11/29 11:58:49 mdw Exp $
+ *
+ * File descriptor passing
+ *
+ * (c) 2003 Straylight/Edgeware
+ */
+
+/*----- Licensing notice --------------------------------------------------* 
+ *
+ * This file is part of the mLib utilities library.
+ *
+ * mLib is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Library General Public License as
+ * published by the Free Software Foundation; either version 2 of the
+ * License, or (at your option) any later version.
+ * 
+ * mLib is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Library General Public License for more details.
+ * 
+ * You should have received a copy of the GNU Library General Public
+ * License along with mLib; if not, write to the Free
+ * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
+ * MA 02111-1307, USA.
+ */
+
+/*----- Revision history --------------------------------------------------* 
+ *
+ * $Log: fdpass.h,v $
+ * Revision 1.1  2003/11/29 11:58:49  mdw
+ * File descriptor passing.
+ *
+ */
+
+#ifndef MLIB_FDPASS_H
+#define MLIB_FDPASS_H
+
+#ifdef __cplusplus
+  extern "C" {
+#endif
+
+/*----- Header files ------------------------------------------------------*/
+
+#include <sys/types.h>
+#include <unistd.h>
+
+/*----- Functions provided ------------------------------------------------*/
+
+/* --- @fdpass_send@ --- *
+ *
+ * Arguments:  @int sock@ = socket to send over
+ *             @int fd@ = file descriptor to send
+ *             @const void *p@ = pointer to data to send
+ *             @size_t sz@ = size of buffer to send
+ *
+ * Returns:    On error, @-1@, otherwise number of bytes transferred from
+ *             @p@.
+ *
+ * Use:                Sends a copy of file descriptor @fd@ to the other end of
+ *             @sock@.
+ */
+
+extern ssize_t fdpass_send(int /*sock*/, int /*fd*/,
+                          const void */*p*/, size_t /*sz*/);
+
+/* --- @fdpass_recv@ --- *
+ *
+ * Arguments:  @int sock@ = socket to send over
+ *             @int *fd@ = where to put received descriptor
+ *             @void *p@ = pointer to where to put data
+ *             @size_t sz@ = size of buffer
+ *
+ * Returns:    On error, @-1@, otherwise number of bytes transferred.
+ *
+ * Use:                Receives a file descriptor.  If the call succeeds, and there
+ *             was a file descriptor, then @fd@ won't be @-1@ on exit;
+ *             otherwise it will.  At most one descriptor will be collected.
+ */
+
+extern ssize_t fdpass_recv(int /*sock*/, int */*fd*/,
+                          void */*p*/, size_t /*sz*/);
+
+/*----- That's all, folks -------------------------------------------------*/
+
+#ifdef __cplusplus
+  }
+#endif
+
+#endif
diff --git a/man/fdpass.3 b/man/fdpass.3
new file mode 100644 (file)
index 0000000..6a91ec1
--- /dev/null
@@ -0,0 +1,54 @@
+.\" -*-nroff-*-
+.TH fdpass 3 "28 November 2003" "Straylight/Edgeware" "mLib utilities library"
+.SH NAME
+fdpass \- file descriptor passing
+.\" @fdpass_send
+.\" @fdpass_recv
+.SH SYNOPSIS
+.nf
+.B "#include <mLib/fdpass.h>"
+
+.BI "ssize_t fdpass_send(int " sock ", int " fd ", const void *" p ", size_t " sz );
+.BI "ssize_t fdpass_recv(int " sock ", int *" fd ", void *" p ", size_t " sz );
+.fi
+.SH DESCRIPTION
+The function
+.B fdpass_send
+sends the file descriptor
+.I fd
+as ancillary data attached to the buffer pointed to by
+.I p
+of length
+.I sz
+over the Unix-domain socket
+.IR sock .
+It returns the amount of data sent, or \-1 on error.  For more details,
+see
+.BR sendmsg (2)
+and
+.BR unix (7).
+.PP
+The function
+.B fdpass_recv
+receives at most
+.I sz
+bytes of data into the buffer pointed to by
+.IR p ,
+together with at most one file descriptor passed as ancillary data,
+which is written to the integer pointed to by
+.IR fd .
+Other file descriptors received are closed; any other ancillary messages
+are ignored.  If no file descriptor is received, 
+.BI * fd
+is set to \-1.  The function returns the number of bytes read, or \-1 on
+error.  For more details, see
+.BR recvmsg (2)
+and
+.BR unix (7).
+.SH "SEE ALSO"
+.BR recvmsg (2),
+.BR sendmsg (2),
+.BR mLib (3),
+.BR unix (7).
+.SH AUTHOR
+Mark Wooding, <mdw@nsict.org>