This file is indexed.

/usr/include/BoxLib/Utility.H is in libbox-dev 2.5-2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
/*
** (c) 1996-2000 The Regents of the University of California (through
** E.O. Lawrence Berkeley National Laboratory), subject to approval by
** the U.S. Department of Energy.  Your use of this software is under
** license -- the license agreement is attached and included in the
** directory as license.txt or you may contact Berkeley Lab's Technology
** Transfer Department at TTD@lbl.gov.  NOTICE OF U.S. GOVERNMENT RIGHTS.
** The Software was developed under funding from the U.S. Government
** which consequently retains certain rights as follows: the
** U.S. Government has been granted for itself and others acting on its
** behalf a paid-up, nonexclusive, irrevocable, worldwide license in the
** Software to reproduce, prepare derivative works, and perform publicly
** and display publicly.  Beginning five (5) years after the date
** permission to assert copyright is obtained from the U.S. Department of
** Energy, and subject to any subsequent five (5) year renewals, the
** U.S. Government is granted for itself and others acting on its behalf
** a paid-up, nonexclusive, irrevocable, worldwide license in the
** Software to reproduce, prepare derivative works, distribute copies to
** the public, perform publicly and display publicly, and to permit
** others to do so.
*/

#ifndef BL_UTILITY_H
#define BL_UTILITY_H
//
// $Id: Utility.H,v 1.53 2002/10/24 21:56:00 lijewski Exp $
//
#include <winstd.H>

#include <iostream>
#include <string>

#ifndef WIN32
#include <sys/types.h>
#include <sys/wait.h>
#endif

#include <BLassert.H>
#include <REAL.H>

//
//@Man:
//@Memo: Useful C++ Utility Functions
/*@Doc:

  This data-less class is a poor-person's namespace of utility functions.
  Since we can't assume the existence of namespaces, and we don't
  like global functions, we put them into a data-less class as
  static member functions.
*/

namespace BoxLib
{
    /*@ManDoc: Returns the total user and system time used by
      the calling process up to the point of the call.
      If t != 0, it also stores the result in t.
    */
    double second (double* t = 0);

    /*@ManDoc: Returns the current time as the number of microseconds
               relative to program startup.  If t != 0, it also
               stores the result in t.
    */
    double wsecond (double* t = 0);
    //
    //@ManDoc: Reset start of Wall Clock Time for wsecond() to NOW.
    //
    void ResetWallClockTime ();
    //
    //@ManDoc: Return true if argument is a non-zero length string of digits.
    //
    bool is_integer (const char* str);
    //
    //@ManDoc: Returns rootNNNN where NNNN == num.
    //
    std::string Concatenate (const std::string& root,
                             int                num);

    /*@ManDoc:
      Creates the specified directories.  `path' may be either a full pathname
      or a relative pathname.  It will create all the directories in the
      pathname, if they don't already exist, so that on successful return the
      pathname refers to an existing directory.  Returns true or false
      depending upon whether or not all it was successful.  Also returns
      if `path' is NULL or "/".  `mode' is the mode passed to mkdir() for
      any directories that must be created.
    
      For example, if it is passed the string "/a/b/c/d/e/f/g", it
      will return successfully when all the directories in the pathname
      exist; i.e. when the full pathname is a valid directory.

      In a Windows environment, the path separator is a '\', so that if using
      the example given above you must pass the string  
      "\\a\\b\\c\\d\\e\\f\\g"  (Note that you must escape the backslash in a
      character string), 
    */
    bool UtilCreateDirectory (const std::string& path,
                              mode_t             mode);
    //
    //@ManDoc: Output a message and abort when couldn't create the directory.
    //
    void CreateDirectoryFailed (const std::string& dir);
    //
    //@ManDoc: Output a message and abort when couldn't open the file.
    //
    void FileOpenFailed (const std::string& dir);
    //
    //@ManDoc: Attempt to unlink the file.  Ignore any errors.
    //
    void UnlinkFile (const std::string& file);

    /*@ManDoc: Aborts after printing message indicating out-of-memory;
               i.e. operator new has failed. This is the "supported"
               set\_new\_handler() function for BoxLib applications.
     */
    void OutOfMemory ();

    /*@ManDoc:

      This function returns an approximation of the inverse cumulative
      standard normal distribution function.  I.e., given P, it returns
      an approximation to the X satisfying P = Pr{Z <= X} where Z is a
      random variable from the standard normal distribution.

      The algorithm uses a minimax approximation by rational functions
      and the result has a relative error whose absolute value is less
      than 1.15e-9.

      If "best" is true the approximation is further refined down to more
      or less machine precision using one iteration of Halley's Rational
      Method.

      Author:      Peter J. Acklam
      Time-stamp:  2002-06-09 18:45:44 +0200
      E-mail:      jacklam@math.uio.no
      WWW URL:     http://www.math.uio.no/~jacklam

      C implementation adapted from Peter's Perl version.

      "p" MUST be in the open interval (0,1).

      There are two entry points for Fortran:
    
      REAL\_T val
      call blinvnormdist(val)

      and

      REAL\_T val
      call blinvnormdistbest(val)

      Internally, these Fortran entry points call a static Mersenne Twister
      object (the same one called by blutilrand()) to get a random number in
      the open interval (0,1), and then sets "val" to the result of calling
      BoxLib::InvNormDist() with that random number.
     */
    double InvNormDist (double p, bool best = false);

    /*@ManDoc:
      Mersenne Twister pseudo-random number generator.

      Generates one pseudorandom real number (double) which is
      uniformly distributed on [0,1]-interval for each call.

      Accepts any 32-bit integer as a seed -- uses 4357 as the default.

      Has a period of 2**19937.

      Mersenne Twister Home Page: http://www.math.keio.ac.jp/matumoto/emt.html

      There is also an entry point for Fortran callable as:
    
      REAL\_T rn
      call blutilrand(rn)

      Internally, blutilrand() calls a static Mersenne Twister oject (the
      same one used by BoxLib::Random()) to get a value in [0,1] and then
      sets "rn" to that value.
    */
    double Random ();

    /*@ManDoc: Set the seed of the random number generator.

      There is also an entry point for Fortran callable as:

      INTEGER seed
      call blutilinitrand(seed)
    */
    void InitRandom (unsigned long seed);

    /*@ManDoc: Try to execute a shell command in a subshell.
               User is responsible for calling waitpid() on the pid
	       returned from this function.
    */
    pid_t Execute (const char* cmd);
    //
    // Helper class for Times, used in Threads, Profiling, and Timers.
    //
    class Time
    {
    public:
	Time();
	Time(long s, long n = 0);
	Time(double d);
	double as_double() const;
	long as_long() const;
	Time& operator+=(const Time&);
	Time operator+(const Time&) const;
	static Time get_time();
    private:
	long tv_sec;
	long tv_nsec;
	void normalize();
    };
    //
    // Implements a simple in place Timer:
    //
    template <double (*FCN)(double*)> class base_Timer;
    template <double (*FCN)(double*)> std::ostream& operator<<(std::ostream&, const base_Timer<FCN>&);

    typedef base_Timer<BoxLib::wsecond> WallTimer;
    typedef base_Timer<BoxLib::second>  CPUTimer;

    template <double (*FCN)(double*)>
    class base_Timer
    {
    public:
	class bad_timer;
	base_Timer();
	~base_Timer();
	void start();
	void stop();
	void reset();
	double time() const;
	double accum_time() const;
	int count() const;
	bool is_running() const;
	static double tick();
    private:
	bool running;
	double val;
	double held;
	double accum_val;
	int cnt;
    };
    //
    // The Mersenne twistor :
    //
    class mt19937
    {
    public:
	typedef unsigned long seed_type;
	explicit mt19937 (seed_type seed = 4357UL);
	mt19937 (seed_type array[], int array_len);
	void rewind();
	
	double d1_value ();	// [0,1] random numbers
	double d_value ();	// [0,1) random numbers
	long l_value ();	// [0,2^31-1] random numbers
	unsigned long u_value (); // [0,2^32-1] random numbers
    private:
	void sgenrand (unsigned long seed);
	void sgenrand (seed_type seed_array[], int len);
	unsigned long igenrand ();
	void reload ();
    private:
	enum { N = 624 };
	unsigned long init_seed;
	unsigned long mt[N];	// the array for the state vector
	int mti;		// mti==N+1 means mt[N] is not initialized
    };

    class expect;
    std::istream& operator>>(std::istream&, const expect& exp);
    
    class expect
    {
	friend std::istream& operator>>(std::istream&, const expect& exp);
    public:
	explicit expect(const std::string& str_);
	explicit expect(const char* istr_);
	explicit expect(char c);
	const std::string& the_string() const;
    private:
	std::string istr;
    };
}

//
// I'm going to document right here all the BL macros that aren't documented
// anywhere else.  Note that all these #ifdef ... #endif blocks are necessary
// to get doc++ to properly document the macros.
//

#ifdef BL_ARCH_CRAY
#undef BL_ARCH_CRAY
/*@ManDoc:
  The macro BL\_ARCH\_CRAY is defined only when compiling on a Cray
  architecture.  The make subsystem automatically sets this if it
  detects that a compilation is taking place on a Cray system.
*/
#define BL_ARCH_CRAY 1
#endif /*BL_ARCH_CRAY*/

#ifdef BL_LANG_FORT
#undef BL_LANG_FORT
/*@ManDoc:
  The macro BL\_LANG\_FORT indicates that Fortran code is being compiled.
*/
#define BL_LANG_FORT 1
#endif /*BL_LANG_FORT*/

#ifdef BL_LANG_CC
#undef BL_LANG_CC
/*@ManDoc:
  The macro BL\_LANG\_CC indicates that C++ code is being compiled.
*/
#define BL_LANG_CC 1
#endif /*BL_LANG_CC*/

#ifdef BL_FORT_USE_UNDERSCORE
#undef BL_FORT_USE_UNDERSCORE
/*@ManDoc:
  The macro BL\_FORT\_USE\_UNDERSCORE indicates that C++ code should call
  Fortran routines by appending an underscore to the name of the Fortran
  routine.  This is set automatically by the make subsystem.  It is the
  default for all BoxLib-style programs except on Cray architectures.

  For example, if the Fortran routine is named abcxyx, then it will
  be called in C++ code as abcxyz\_.
*/
#define BL_FORT_USE_UNDERSCORE 1
#endif /*BL_FORT_USE_UNDERSCORE*/

#ifdef BL_FORT_USE_UPPERCASE
#undef BL_FORT_USE_UPPERCASE
/*@ManDoc:
  The macro BL\_FORT\_USE\_UPPERCASE indicates that C++ code should call
  Fortran routines using uppercase letters for all the letters in the
  routine.  This is set automatically by the make subsystem.  Currently it
  is only set when compiling on Cray architectures.

  For example, if the Fortran routine is named abcxyx, then it will
  be called in C++ code as ABCXYZ.
*/
#define BL_FORT_USE_UPPERCASE 1
#endif /*BL_FORT_USE_UPPERCASE*/

#ifdef BL_FORT_USE_LOWERCASE
#undef BL_FORT_USE_LOWERCASE
/*@ManDoc:
  The macro BL\_FORT\_USE\_LOWERCASE indicates that C++ code should call
  Fortran routines using lowercase letters for all the letters in the
  routine.  This is set automatically by the make subsystem.  

  For example, if the Fortran routine is named abcxyx, then it will
  be called in C++ code as abcxyx.
*/
#define BL_FORT_USE_LOWERCASE 1
#endif /*BL_FORT_USE_LOWERCASE*/

/*@ManDoc:
  BL\_IGNORE\_MAX is a macro that expands to the literal value 100000.  It is
  defined when compiling either Fortran or C++ code; i.e. when either
  BL\_LANG\_CC or BL\_LANG\_FORT is defined.  It is used in calls to
  istream::ignore() in the BoxLib code when reading in characters from an
  istream.  We use this macro instead of the more proper INT\_MAX from
  <limits.h> since at least one compiler didn't work properly when
  istream::ignore() was passed INT\_MAX.
*/
#define BL_IGNORE_MAX 100000

// Implementation of the Timer

template <double (*FCN)(double*)>
BoxLib::base_Timer<FCN>::base_Timer()
    : running(false), val(0.0), accum_val(0.0), cnt(0)
{
}

template <double (*FCN)(double*)>
BoxLib::base_Timer<FCN>::~base_Timer()
{
    BL_ASSERT( !running );
}

template <double (*FCN)(double*)>
bool
BoxLib::base_Timer<FCN>::is_running() const
{
    return running;
}

template <double (*FCN)(double*)>
inline
void
BoxLib::base_Timer<FCN>::start()
{
    BL_ASSERT( !running );
    held = FCN(0);
    running = true;
}

template <double (*FCN)(double*)>
inline
void
BoxLib::base_Timer<FCN>::stop()
{
    BL_ASSERT( running );
    val = (FCN(0) - held);
#ifndef NDEBUG
    if ( val < 0 )
    {
	std::cout << "Got a negative time " << val << "!" << std::endl;
    }
#endif
    accum_val += val;
    cnt += 1;
    running = false;
}

template <double (*FCN)(double*)>
void
BoxLib::base_Timer<FCN>::reset()
{
    BL_ASSERT( !running );
    accum_val = 0;
    cnt = 0;
}

template <double (*FCN)(double*)>
double
BoxLib::base_Timer<FCN>::accum_time() const
{
    BL_ASSERT( !running );
    return accum_val;
}

template <double (*FCN)(double*)>
double
BoxLib::base_Timer<FCN>::time() const
{
    BL_ASSERT( !running );
    return val;
}

template <double (*FCN)(double*)>
int
BoxLib::base_Timer<FCN>::count() const
{
    BL_ASSERT( !running );
    return cnt;
}

// I stole this code from someplace, but I don't know where.
template <double (*FCN)(double*)>
double
BoxLib::base_Timer<FCN>::tick()
{
    const int M = 100;
    double timesfound[M];

    //  Collect a sequence of M unique time values from the system.

    for ( int i = 0; i < M; ++i )
    {
	double t2;
	double t1 = FCN(0);
	while( ((t2 = FCN(0)) - t1) == 0 )
	{
	}
	timesfound[i] = t2;
    }

    double minDelta = timesfound[1] - timesfound[0];
    for ( int i = 2; i < M; i++ )
    {
	minDelta = std::min(minDelta, std::max(timesfound[i]-timesfound[i-1], 0.0));
    }
    return minDelta;
}

template <double (*FCN)(double*)>
std::ostream& operator<<(std::ostream& os, const BoxLib::base_Timer<FCN>& bt)
{
    return os << "["
	      << bt.accum_time() << "/"
	      << bt.count()
	      << "]";
}

#endif /*BL_UTILITY_H*/