1.\"- 2.\" Copyright (c) 2007 Dag-Erling Smørgrav 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd July 28, 2017 27.Dt FLOPEN 3 28.Os 29.Sh NAME 30.Nm flopen , 31.Nm flopenat 32.Nd "Reliably open and lock a file" 33.Sh LIBRARY 34.Lb libutil 35.Sh SYNOPSIS 36.In sys/fcntl.h 37.In libutil.h 38.Ft int 39.Fn flopen "const char *path" "int flags" 40.Ft int 41.Fn flopen "const char *path" "int flags" "mode_t mode" 42.Ft int 43.Fn flopenat "int fd" "const char *path" "int flags" 44.Ft int 45.Fn flopenat "int fd" "const char *path" "int flags" "mode_t mode" 46.Sh DESCRIPTION 47The 48.Fn flopen 49function opens or creates a file and acquires an exclusive lock on it. 50It is essentially equivalent with calling 51.Fn open 52with the same parameters followed by 53.Fn flock 54with an 55.Fa operation 56argument of 57.Dv LOCK_EX , 58except that 59.Fn flopen 60will attempt to detect and handle races that may occur between opening 61/ creating the file and locking it. 62Thus, it is well suited for opening lock files, PID files, spool 63files, mailboxes and other kinds of files which are used for 64synchronization between processes. 65.Pp 66If 67.Fa flags 68includes 69.Dv O_NONBLOCK 70and the file is already locked, 71.Fn flopen 72will fail and set 73.Va errno 74to 75.Dv EWOULDBLOCK . 76.Pp 77As with 78.Fn open , 79the additional 80.Fa mode 81argument is required if 82.Fa flags 83includes 84.Dv O_CREAT . 85.Pp 86The 87.Fn flopenat 88function is equivalent to the 89.Fn flopen 90function except in the case where the 91.Fa path 92specifies a relative path. 93In this case the file to be opened is determined relative to the directory 94associated with the file descriptor 95.Fa fd 96instead of the current working directory. 97If 98.Fn flopenat 99is passed the special value 100.Dv AT_FDCWD 101in the 102.Fa fd 103parameter, the current working directory is used 104and the behavior is identical to a call to 105.Fn flopen . 106.Sh RETURN VALUES 107If successful, 108.Fn flopen 109returns a valid file descriptor. 110Otherwise, it returns -1, and sets 111.Va errno 112as described in 113.Xr flock 2 114and 115.Xr open 2 . 116.Sh SEE ALSO 117.Xr errno 2 , 118.Xr flock 2 , 119.Xr open 2 120.Sh AUTHORS 121.An -nosplit 122The 123.Nm 124function and this manual page were written by 125.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . 126