13997c939SPeter Avalos.\"- 2f6e8a0a1SImre Vadasz.\" Copyright (c) 2007 Dag-Erling Coïdan Smørgrav 33997c939SPeter Avalos.\" All rights reserved. 43997c939SPeter Avalos.\" 53997c939SPeter Avalos.\" Redistribution and use in source and binary forms, with or without 63997c939SPeter Avalos.\" modification, are permitted provided that the following conditions 73997c939SPeter Avalos.\" are met: 83997c939SPeter Avalos.\" 1. Redistributions of source code must retain the above copyright 93997c939SPeter Avalos.\" notice, this list of conditions and the following disclaimer. 103997c939SPeter Avalos.\" 2. Redistributions in binary form must reproduce the above copyright 113997c939SPeter Avalos.\" notice, this list of conditions and the following disclaimer in the 123997c939SPeter Avalos.\" documentation and/or other materials provided with the distribution. 133997c939SPeter Avalos.\" 143997c939SPeter Avalos.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 153997c939SPeter Avalos.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 163997c939SPeter Avalos.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 173997c939SPeter Avalos.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 183997c939SPeter Avalos.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 193997c939SPeter Avalos.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 203997c939SPeter Avalos.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 213997c939SPeter Avalos.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 223997c939SPeter Avalos.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 233997c939SPeter Avalos.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 243997c939SPeter Avalos.\" SUCH DAMAGE. 253997c939SPeter Avalos.\" 26d316f7c9SJohn Marino.\" $FreeBSD: head/lib/libutil/flopen.3 229784 2012-01-07 16:13:56Z uqs $ 273997c939SPeter Avalos.\" 28d316f7c9SJohn Marino.Dd June 6, 2009 293997c939SPeter Avalos.Dt FLOPEN 3 303997c939SPeter Avalos.Os 313997c939SPeter Avalos.Sh NAME 323997c939SPeter Avalos.Nm flopen 333997c939SPeter Avalos.Nd "Reliably open and lock a file" 343997c939SPeter Avalos.Sh LIBRARY 353997c939SPeter Avalos.Lb libutil 363997c939SPeter Avalos.Sh SYNOPSIS 373997c939SPeter Avalos.In sys/fcntl.h 383997c939SPeter Avalos.In libutil.h 393997c939SPeter Avalos.Ft int 403997c939SPeter Avalos.Fn flopen "const char *path" "int flags" 413997c939SPeter Avalos.Ft int 423997c939SPeter Avalos.Fn flopen "const char *path" "int flags" "mode_t mode" 433997c939SPeter Avalos.Sh DESCRIPTION 443997c939SPeter AvalosThe 453997c939SPeter Avalos.Fn flopen 463997c939SPeter Avalosfunction opens or creates a file and acquires an exclusive lock on it. 473997c939SPeter AvalosIt is essentially equivalent with calling 483997c939SPeter Avalos.Fn open 49d316f7c9SJohn Marinowith the same parameters followed by 50d316f7c9SJohn Marino.Fn flock 51d316f7c9SJohn Marinowith an 52*78732326SSascha Wildner.Fa operation 53d316f7c9SJohn Marinoargument of 54d316f7c9SJohn Marino.Dv LOCK_EX , 553997c939SPeter Avalosexcept that 563997c939SPeter Avalos.Fn flopen 573997c939SPeter Avaloswill attempt to detect and handle races that may occur between opening 583997c939SPeter Avalos/ creating the file and locking it. 593997c939SPeter AvalosThus, it is well suited for opening lock files, PID files, spool 603997c939SPeter Avalosfiles, mailboxes and other kinds of files which are used for 613997c939SPeter Avalossynchronization between processes. 623997c939SPeter Avalos.Pp 633997c939SPeter AvalosIf 64*78732326SSascha Wildner.Fa flags 653997c939SPeter Avalosincludes 663997c939SPeter Avalos.Dv O_NONBLOCK 673997c939SPeter Avalosand the file is already locked, 683997c939SPeter Avalos.Fn flopen 693997c939SPeter Avaloswill fail and set 703997c939SPeter Avalos.Va errno 713997c939SPeter Avalosto 72a814a13fSSascha Wildner.Er EWOULDBLOCK . 733997c939SPeter Avalos.Pp 743997c939SPeter AvalosAs with 753997c939SPeter Avalos.Fn open , 763997c939SPeter Avalosthe additional 77*78732326SSascha Wildner.Fa mode 783997c939SPeter Avalosargument is required if 79*78732326SSascha Wildner.Fa flags 803997c939SPeter Avalosincludes 813997c939SPeter Avalos.Dv O_CREAT . 823997c939SPeter Avalos.Sh RETURN VALUES 833997c939SPeter AvalosIf successful, 843997c939SPeter Avalos.Fn flopen 853997c939SPeter Avalosreturns a valid file descriptor. 863997c939SPeter AvalosOtherwise, it returns -1, and sets 873997c939SPeter Avalos.Va errno 883997c939SPeter Avalosas described in 89d316f7c9SJohn Marino.Xr flock 2 903997c939SPeter Avalosand 913997c939SPeter Avalos.Xr open 2 . 923997c939SPeter Avalos.Sh SEE ALSO 933997c939SPeter Avalos.Xr errno 2 , 94d316f7c9SJohn Marino.Xr flock 2 , 953997c939SPeter Avalos.Xr open 2 963997c939SPeter Avalos.Sh AUTHORS 973997c939SPeter Avalos.An -nosplit 983997c939SPeter AvalosThe 993997c939SPeter Avalos.Nm 1003997c939SPeter Avalosfunction and this manual page were written by 10198b3d9adSFranco Fichtner.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . 102