1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2024 Oxide Computer Company 13.\" 14.Dd January 12, 2024 15.Dt EXECVEX 2 16.Os 17.Sh NAME 18.Nm execvex 19.Nd execute a file with flags 20.Sh SYNOPSIS 21.In execx.h 22.Ft int 23.Fo execvex 24.Fa "uintptr_t path" 25.Fa "char *const argv[]" 26.Fa "char *const envp[]" 27.Fa "int flags" 28.Fc 29.Sh DESCRIPTION 30.Nm 31is an extended version of 32.Xr execve 2 . 33Like other functions in the 34.Xr exec 2 35family, 36.Nm 37replaces the current process image with a new one indicated by the 38.Ar path 39argument. 40.Pp 41The following values may be bitwise-ORed together in the 42.Fa flags 43argument to modify the behavior of the function: 44.Bl -tag -width Dv 45.It Dv EXEC_DESCRIPTOR 46The 47.Ar path 48argument is the number of an open file descriptor in the current process. 49.El 50.Pp 51If 52.Dv EXEC_DESCRIPTOR 53is not set in 54.Ar flags , 55the 56.Ar path 57argument must be set to a pointer to a pathname of a file which is executable 58by the current process. 59.Pp 60The 61.Xr exec 2 62family of functions are implemented in terms of 63.Nm . 64A call to 65.Pp 66.Dl execve(path, argv, envp) ; 67.Pp 68is equivalent to 69.Pp 70.Dl execvex((uintptr_t)path, argv, envp, 0) ; 71.Pp 72and a call to 73.Pp 74.Dl fexecve(filedes, argv, envp) ; 75.Pp 76is equivalent to 77.Pp 78.Dl execvex((uintptr_t)filedes, argv, envp, EXEC_DESCRIPTOR) ; 79.Sh RETURN VALUES 80If 81.Nm 82returns to the calling process image, an error has occurred; the return 83value is \-1 and 84.Va errno 85is set to indicate the error. 86.Sh ERRORS 87.Nm 88will fail if: 89.Bl -tag -width Er 90.It Er EINVAL 91The flags argument is invalid. 92.El 93.Pp 94.Nm may also fail for any of the reasons listed in 95.Xr exec 2 . 96.Sh INTERFACE STABILITY 97.Sy Committed 98.Sh MT-LEVEL 99.Sy Async-Signal-Safe 100.Sh SEE ALSO 101.Xr exec 2 102