E-MailRelay

gpidfile.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
3//
4// This program is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with this program. If not, see <http://www.gnu.org/licenses/>.
16// ===
17///
18/// \file gpidfile.h
19///
20
21#ifndef G_PIDFILE_H
22#define G_PIDFILE_H
23
24#include "gdef.h"
25#include "gexception.h"
26#include "gsignalsafe.h"
27#include "gprocess.h"
28#include "gpath.h"
29#include <sys/types.h>
30#include <string>
31
32 namespace G
33{
34 class PidFile ;
35 class Daemon ;
36}
37
38//| \class G::PidFile
39/// A class for creating pid files. Works with G::Root and G::Daemon so that
40/// the pid file can get created very late in a daemon startup sequence.
41/// Installs a signal handler so that the pid file gets deleted on process
42/// termination.
43///
44/// Usage:
45/// \code
46/// G::PidFile pid_file ;
47/// if( !path.empty() )
48/// { pid_file.init(path) ; pid_file.check() ; }
49/// G::Root::init("nobody") ;
50/// if( daemon ) G::Daemon::detach( pid_file ) ;
51/// { G::Root claim_root ; pid_file.commit() ; }
52/// \endcode
53///
54/// \see G::Daemon
55///
56 class G::PidFile
57{
58 public:
59 G_EXCEPTION( Error , "invalid pid file" ) ;
60
61 static bool cleanup( SignalSafe , const char * path ) noexcept ;
62 ///< Deletes the specified pid file if it contains this
63 ///< process's id. Claims root privilege to read and
64 ///< delete the pid file (see G::Root::atExit()).
65 ///<
66 ///< This is not normally needed by client code since it
67 ///< is installed as a signal handler (see G::Cleanup)
68 ///< and called from the destructor.
69 ///<
70 ///< Signal-safe, reentrant implementation.
71
72 explicit PidFile( const Path & pid_file_path ) ;
73 ///< Constructor. The path should normally be an
74 ///< absolute path. Use commit() to actually create
75 ///< the file.
76
77 PidFile() ;
78 ///< Default constructor. Constructs a do-nothing
79 ///< object. Initialise with init().
80
81 void init( const Path & pid_file_path ) ;
82 ///< Used after default construction to make the object
83 ///< active. Use commit() to actually create the file.
84
85 ~PidFile() ;
86 ///< Destructor. Calls cleanup() to delete the file.
87
88 void commit() ;
89 ///< Creates the file and installs signal handlers to
90 ///< cleanup() the file on abnormal process termination.
91 ///<
92 ///< Does nothing if no pid file path has been defined.
93 ///< Throws on error.
94 ///<
95 ///< The caller is responsible for setting the file
96 ///< ownership and permissions by switching effecive
97 ///< user-id and umask.
98
99 bool committed() const ;
100 ///< Returns true if commit() has been called with
101 ///< a valid path().
102
103 void check() ;
104 ///< Throws an exception if the path is not absolute.
105 ///< The use of G::Daemon normally requires an absolute
106 ///< path because it may change the current working
107 ///< directory.
108
109 Path path() const ;
110 ///< Returns the path as supplied to the constructor
111 ///< or init().
112
113 public:
114 PidFile( const PidFile & ) = delete ;
115 PidFile( PidFile && ) = delete ;
116 void operator=( const PidFile & ) = delete ;
117 void operator=( PidFile && ) = delete ;
118
119 private:
120 static void create( const Path & pid_file ) ;
121 static Process::Id read( SignalSafe , const char * path ) noexcept ;
122 bool valid() const ;
123
124 private:
125 Path m_path ;
126 bool m_committed{false} ;
127} ;
128
129#endif
G::Path
A Path object represents a file system path.
Definition: gpath.h:72
G::PidFile
A class for creating pid files.
Definition: gpidfile.h:57
G::PidFile::committed
bool committed() const
Returns true if commit() has been called with a valid path().
Definition: gpidfile.cpp:141
G::PidFile::commit
void commit()
Creates the file and installs signal handlers to cleanup() the file on abnormal process termination.
Definition: gpidfile.cpp:132
G::PidFile::PidFile
PidFile()
Default constructor.
G::PidFile::check
void check()
Throws an exception if the path is not absolute.
Definition: gpidfile.cpp:126
G::PidFile::~PidFile
~PidFile()
Destructor. Calls cleanup() to delete the file.
Definition: gpidfile.cpp:36
G::PidFile::path
Path path() const
Returns the path as supplied to the constructor or init().
Definition: gpidfile.cpp:146
G::PidFile::cleanup
static bool cleanup(SignalSafe, const char *path) noexcept
Deletes the specified pid file if it contains this process's id.
Definition: gpidfile.cpp:106
G::PidFile::init
void init(const Path &pid_file_path)
Used after default construction to make the object active.
Definition: gpidfile.cpp:54
G::Process::Id
Process-id class.
Definition: gprocess.h:140
G::SignalSafe
An empty structure that is used to indicate a signal-safe, reentrant implementation.
Definition: gsignalsafe.h:37
gexception.h
gpath.h
gprocess.h
gsignalsafe.h
G
Low-level classes.
Definition: galign.h:28