1.\"- 2.\" Copyright (c) 2007 Dag-Erling Coïdan 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.\" $FreeBSD$ 27.\" 28.Dd July 28, 2017 29.Dt FLOPEN 3 30.Os 31.Sh NAME 32.Nm flopen , 33.Nm flopenat 34.Nd "Reliably open and lock a file" 35.Sh LIBRARY 36.Lb libutil 37.Sh SYNOPSIS 38.In sys/fcntl.h 39.In libutil.h 40.Ft int 41.Fn flopen "const char *path" "int flags" 42.Ft int 43.Fn flopen "const char *path" "int flags" "mode_t mode" 44.Ft int 45.Fn flopenat "int fd" "const char *path" "int flags" 46.Ft int 47.Fn flopenat "int fd" "const char *path" "int flags" "mode_t mode" 48.Sh DESCRIPTION 49The 50.Fn flopen 51function opens or creates a file and acquires an exclusive lock on it. 52It is essentially equivalent with calling 53.Fn open 54with the same parameters followed by 55.Fn flock 56with an 57.Fa operation 58argument of 59.Dv LOCK_EX , 60except that 61.Fn flopen 62will attempt to detect and handle races that may occur between opening 63/ creating the file and locking it. 64Thus, it is well suited for opening lock files, PID files, spool 65files, mailboxes and other kinds of files which are used for 66synchronization between processes. 67.Pp 68If 69.Fa flags 70includes 71.Dv O_NONBLOCK 72and the file is already locked, 73.Fn flopen 74will fail and set 75.Va errno 76to 77.Dv EWOULDBLOCK . 78.Pp 79As with 80.Fn open , 81the additional 82.Fa mode 83argument is required if 84.Fa flags 85includes 86.Dv O_CREAT . 87.Pp 88The 89.Fn flopenat 90function is equivalent to the 91.Fn flopen 92function except in the case where the 93.Fa path 94specifies a relative path. 95In this case the file to be opened is determined relative to the directory 96associated with the file descriptor 97.Fa fd 98instead of the current working directory. 99If 100.Fn flopenat 101is passed the special value 102.Dv AT_FDCWD 103in the 104.Fa fd 105parameter, the current working directory is used 106and the behavior is identical to a call to 107.Fn flopen . 108.Sh RETURN VALUES 109If successful, 110.Fn flopen 111returns a valid file descriptor. 112Otherwise, it returns -1, and sets 113.Va errno 114as described in 115.Xr flock 2 116and 117.Xr open 2 . 118.Sh SEE ALSO 119.Xr errno 2 , 120.Xr flock 2 , 121.Xr open 2 122.Sh AUTHORS 123.An -nosplit 124The 125.Nm 126function and this manual page were written by 127.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . 128