.\" -*-nroff-*-
.\"
.\" Manual for file descriptor passing
.\"
.\" (c) 2003, 2005, 2007, 2009, 2024 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.
.
.\"--------------------------------------------------------------------------
.so ../defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH fdpass 3mLib "28 November 2003" "Straylight/Edgeware" "mLib utilities library"
.\" @fdpass_send
.\" @fdpass_recv
.
.\"--------------------------------------------------------------------------
.SH NAME
fdpass \- file descriptor passing
.
.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.
.nf
.B "#include <mLib/fdpass.h>"
.PP
.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@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------