dup3;

#if __BSD_VISIBLE

int	 dup3(int, int, int);

#endif

.In fcntl.h

.Ft int

.Fn dup3 "int oldd" "int newd" "int flags"

The

.Fn dup3

function is otherwise much the same as

.Fn dup2

with the added ability to automatically set certain

important flags to the resulting new file descriptor.

.br

By setting the bit

.Dv O_CLOEXEC

in the flags one can mark the resulting file descriptor be

automatically closed during

.Fn execve

and other functions in the

.Fn exec*

family.

Since this feature is activated atomically inside the kernel

there is no risk that even in a threaded code another thread

could call any of the

.Fn exec*

functions before the descriptor has been marked to be closed.

.br

Setting the bit

.Dv O_NONBLOCK

in the flags marks the resulting file descriptor for non-blocking I/O.

.sp

There a couple of features in

.Fn dup3

which can have an impact on portability.

.br

Currently this implementation of

.Fn dup3

does not support the

.Nx

feature

.Dv O_NOSIGPIPE .

.br

Because the

.Fx

kernel can properly handle the case when

.Fa oldd

==

.Fa newd

this implementation of

.Fn dup3 

will not return an error like 

.Fn dup3 

on Linux when it receives two equal file descriptors as arguments.

Instead this implementation intentionally behaves like

.Fn dup3

in

.Nx

and sets the flags on the resulting file descriptor.

Thus any code that has worked on Linux should

work fine also on

.Fx

and/or

.Nx ,

but porting to the other direction may cause hiccups.

.Pp

Unlike the other two functions

.Fn dup3

is not implemented as a genuine system call but as a normal library function

depending on the features provided by the

.Fn fcntl

system call.

.Pp

.sp

.sp

The 

.Fn dup3

function fails if:

.Bl -tag -width Er

.It Bq Er EBADF

The

.Fa oldd

argument is not a valid active descriptor or the

.Fa newd

argument is negative or exceeds the maximum allowable descriptor number

.It Bq Er EINVAL

The

.Fa flags

argument containes unsupported bits.

Currently the only accepted bits are

.Dv O_CLOEXEC 

and

.Dv O_NONBLOCK .

.El

.br

Currently the

.Fn dup3

entry is not dictated by any standard.

It is simply a natural extension the other two variants and

a compatibility feature to match a similar extension in other

UNIX like systems.

.br

The

.Fn dup3

function appeared in

.Fx 9.1

STABLE branch.

/*-

 * Copyright (c) 2012 Jukka A. Ukkonen

 * All rights reserved.

 *

 * This software was developed by Jukka Ukkonen for FreeBSD.

 *

 * Redistribution and use in source and binary forms, with or without

 * modification, are permitted provided that the following conditions

 * are met:

 * 1. Redistributions of source code must retain the above copyright

 *    notice, this list of conditions and the following disclaimer.

 * 2. Redistributions in binary form must reproduce the above copyright

 *    notice, this list of conditions and the following disclaimer in the

 *    documentation and/or other materials provided with the distribution.

 *

 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND

 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE

 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS

 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

 * SUCH DAMAGE.

 */

#include <sys/cdefs.h>

__FBSDID("$FreeBSD$");

#include "namespace.h"

#include <unistd.h>

#include <fcntl.h>

#include <errno.h>

#include "un-namespace.h"

/*

 * A bunch of checks just in case someone

 * tries to compile this on a too old system.

 */

#if !defined(F_DUP2FD_CLOEXEC) && defined(_F_DUP2FD_CLOEXEC)

#  define F_DUP2FD_CLOEXEC  _F_DUP2FD_CLOEXEC

#endif

#if !defined(F_DUP2FD_CLOEXEC)

#  error Neither F_DUP2FD_CLOEXEC nor _F_DUP2FD_CLOEXEC defined!

#endif

#if !defined(F_DUP2FD)

#  error F_DUP2FD not defined!

#endif

#if !defined(O_CLOEXEC)

#  error O_CLOEXEC not defined!

#endif

/*

 * In case FreeBSD ever becomes O_NOSIGPIPE aware,

 * we will instantly start using it.

 */

#if !defined(O_NOSIGPIPE)

#  define O_NOSIGPIPE	0

#endif

int

__dup3 (oldfd, newfd, flags)

	int oldfd;

	int newfd;

	int flags;

{

	int how;

	int ret;

#if 0

	/*

	 * This would be how Linux does it

	 * in pointlessly restrictive style.

	 * NetBSD does not do this.

	 * FreeBSD can also handle this case

	 * properly.

	 * ==> Anything which works on Linux

	 * will work also on {Free,Net}BSD.

	 * BSD code on Linux may experience

	 * hiccups, if someone relies on

	 * oldfd == newfd.

	 */

	if (oldfd == newfd) {

		errno = EINVAL;

		return (-1);

	}

#endif

	if (flags & ~(O_CLOEXEC | O_NONBLOCK | O_NOSIGPIPE)) {

		errno = EINVAL;

		return (-1);

	}

	how = (flags & O_CLOEXEC) ? F_DUP2FD_CLOEXEC : F_DUP2FD;

	ret = _fcntl (oldfd, how, newfd);

	if (ret < 0)

		return (-1);

	newfd = ret;

	if (flags & (O_NONBLOCK | O_NOSIGPIPE)) {

		int flags2;

		flags2 = _fcntl (newfd, F_GETFL, 0);

		flags2 |= (flags & (O_NONBLOCK | O_NOSIGPIPE));

		(void) _fcntl (newfd, F_SETFL, flags2);

	}

	return (newfd);

}

__weak_reference(__dup3, dup3);

__weak_reference(__dup3, _dup3);