chiark - git - mdw - mLib/blob - sys/fdpass.3

   1 .\" -*-nroff-*-
   2 .TH fdpass 3 "28 November 2003" "Straylight/Edgeware" "mLib utilities library"
   3 .SH NAME
   4 fdpass \- file descriptor passing
   5 .\" @fdpass_send
   6 .\" @fdpass_recv
   7 .SH SYNOPSIS
   8 .nf
   9 .B "#include <mLib/fdpass.h>"
  10
  11 .BI "ssize_t fdpass_send(int " sock ", int " fd ", const void *" p ", size_t " sz );
  12 .BI "ssize_t fdpass_recv(int " sock ", int *" fd ", void *" p ", size_t " sz );
  13 .fi
  14 .SH DESCRIPTION
  15 The function
  16 .B fdpass_send
  17 sends the file descriptor
  18 .I fd
  19 as ancillary data attached to the buffer pointed to by
  20 .I p
  21 of length
  22 .I sz
  23 over the Unix-domain socket
  24 .IR sock .
  25 It returns the amount of data sent, or \-1 on error.  For more details,
  26 see
  27 .BR sendmsg (2)
  28 and
  29 .BR unix (7).
  30 .PP
  31 The function
  32 .B fdpass_recv
  33 receives at most
  34 .I sz
  35 bytes of data into the buffer pointed to by
  36 .IR p ,
  37 together with at most one file descriptor passed as ancillary data,
  38 which is written to the integer pointed to by
  39 .IR fd .
  40 Other file descriptors received are closed; any other ancillary messages
  41 are ignored.  If no file descriptor is received,
  42 .BI * fd
  43 is set to \-1.  The function returns the number of bytes read, or \-1 on
  44 error.  For more details, see
  45 .BR recvmsg (2)
  46 and
  47 .BR unix (7).
  48 .SH "SEE ALSO"
  49 .BR recvmsg (2),
  50 .BR sendmsg (2),
  51 .BR mLib (3),
  52 .BR unix (7).
  53 .SH AUTHOR
  54 Mark Wooding, <mdw@distorted.org.uk>