A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
system-path.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2008 INRIA
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Authors: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
7 */
8#ifndef SYSTEM_PATH_H
9#define SYSTEM_PATH_H
10
11#include <list>
12#include <string>
13
14/**
15 * \file
16 * \ingroup systempath
17 * ns3::SystemPath declarations.
18 */
19
20namespace ns3
21{
22
23/**
24 * \ingroup system
25 * \defgroup systempath Host Filesystem
26 * \brief Encapsulate OS-specific functions to manipulate file
27 * and directory paths.
28 *
29 * The functions provided here are used mostly to implement
30 * the ns-3 test framework.
31 */
32
33/**
34 * \ingroup systempath
35 * \brief Namespace for various file and directory path functions.
36 */
37namespace SystemPath
38{
39
40/**
41 * \ingroup systempath
42 * Get the file system path to the current executable.
43 *
44 * This path is only equivalent to the current working directory when
45 * the executable is executed in its parent directory.
46 *
47 * \return The directory in which the currently-executing binary is located
48 */
49std::string FindSelfDirectory();
50
51/**
52 * \ingroup systempath
53 * Join two file system path elements.
54 *
55 * \param [in] left A path element
56 * \param [in] right A path element
57 * \return A concatenation of the two input paths
58 */
59std::string Append(std::string left, std::string right);
60
61/**
62 * \ingroup systempath
63 * Split a file system path into directories according to
64 * the local path separator.
65 *
66 * This is the inverse of Join.
67 *
68 * \param [in] path A path
69 * \return A list of path elements that can be joined together again with
70 * the Join function.
71 * \sa ns3::SystemPath::Join
72 */
73std::list<std::string> Split(std::string path);
74
75/**
76 * Join a list of file system path directories into a single
77 * file system path.
78 *
79 * This is the inverse of Split.
80 *
81 * \ingroup systempath
82 * \param [in] begin Iterator to first element to join
83 * \param [in] end Iterator to one past the last element to join
84 * \return A path that is a concatenation of all the input elements.
85 */
86std::string Join(std::list<std::string>::const_iterator begin,
87 std::list<std::string>::const_iterator end);
88
89/**
90 * \ingroup systempath
91 * Get the list of files located in a file system directory.
92 *
93 * \param [in] path A path which identifies a directory
94 * \return A list of the filenames which are located in the input directory
95 */
96std::list<std::string> ReadFiles(std::string path);
97
98/**
99 * \ingroup systempath
100 * Get the name of a temporary directory.
101 *
102 * The returned path identifies a directory which does not exist yet.
103 * Call ns3::SystemPath::MakeDirectories to create it. Yes, there is a
104 * well-known security race in this API but we don't care in ns-3.
105 *
106 * The final path to the directory is going to look something like
107 *
108 * /tmp/ns3.14.30.29.32767
109 *
110 * The first part, "/tmp/" is the absolute path found by inspecting
111 * the environment variables `TMP`and `TEMP`, in order. If neither
112 * exists the hard-coded root path `/tmp/` is used.
113 *
114 * The directory name itself starts with the "ns3" identifier telling folks
115 * who is making all of the temp directories.
116 *
117 * The next three numbers give the hour, minute and second, separated by
118 * periods.
119 *
120 * The final number is randomly generated, to avoid name collisions.
121 *
122 * \return A path which identifies a temporary directory.
123 */
124std::string MakeTemporaryDirectoryName();
125
126/**
127 * \ingroup systempath
128 * Create all the directories leading to path.
129 *
130 * \param [in] path A path to a directory
131 */
132void MakeDirectories(std::string path);
133
134/**
135 * \ingroup systempath
136 * Check if a path exists.
137 * Path can be a file or directory.
138 * \param [in] path The path to check.
139 * \returns \c true if the \pname{path} exists.
140 */
141bool Exists(const std::string path);
142
143/**
144 * \ingroup systempath
145 * Replace incompatible characters in a path,
146 * to get a path compatible with different
147 * file systems.
148 * \param [in] path The path to check.
149 * \returns A compatible path.
150 */
151std::string CreateValidSystemPath(const std::string path);
152
153} // namespace SystemPath
154
155} // namespace ns3
156
157#endif /* SYSTEM_PATH_H */
std::list< std::string > ReadFiles(std::string path)
Get the list of files located in a file system directory.
bool Exists(const std::string path)
Check if a path exists.
std::list< std::string > Split(std::string path)
Split a file system path into directories according to the local path separator.
void MakeDirectories(std::string path)
Create all the directories leading to path.
std::string MakeTemporaryDirectoryName()
Get the name of a temporary directory.
std::string Append(std::string left, std::string right)
Join two file system path elements.
std::string Join(std::list< std::string >::const_iterator begin, std::list< std::string >::const_iterator end)
Join a list of file system path directories into a single file system path.
std::string CreateValidSystemPath(const std::string path)
Replace incompatible characters in a path, to get a path compatible with different file systems.
std::string FindSelfDirectory()
Get the file system path to the current executable.
Every class exported by the ns3 library is enclosed in the ns3 namespace.