Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext
symlink (absolute non throwing)

Synchronous symlink creation and open after a precondition.

Description

Note that if creating and you don't specify a target, the target for the symlink is the precondition. On Windows directories are symlinked using a reparse point instead of a symlink due to the default lack of the SeCreateSymbolicLinkPrivilege for non-Administrative users. On Windows you can open symlinks as a file and so a valid handle is output, whereas on POSIX except for Linux you cannot do this and an invalid handle is output. Related types: path_req Be aware that on Windows AFIO operates exclusively in the NT kernel namespace, NOT the Win32 namespace, and therefore paths you supply are converted by afio::path in NT kernel namespace paths. normalise_path() can convert an afio path back to a Filesystem TS path for you, but note that this may not be the path that was supplied originally. NT kernel namespace paths have a 32,767 character limit and an almost POSIX like lack of restrictions on naming or historical behaviour quirks, but as a result AFIO does not support DOS short names or any of the other historical Win32 filing system baggage.

Synopsis
template<class T, typename>
handle_ptr symlink(error_code & _ec, T _path, future<> _target = future<>(),
                   file_flags _flags = file_flags::none)
Parameters

Type

Concept

Name

Description

class T

The type of path to use.

-

Must be specified

-

Must be specified

error_code &

_ec

Error code to set.

T

_path

The filing system path to use.

future<>

_target

The item to link to if creating.

file_flags

_flags

The flags to use.

Returns

A handle to the symlink.

Header

#include <boost/afio/v2/afio.hpp>

Race Guarantees

Operating system Race guarantees under a changing file system
FreeBSD, Linux, OS X, Windows No guarantees.

Complexity

Amortised O(1) to dispatch. Amortised O(1) to complete if symlink creation is constant time.

Exception Model

Propagates the exception of any input precondition with an errored state at the point of dispatch, and throws a std::invalid_argument if any inputs have values which could not possibly be correct. Note that error code returning functions may still throw exceptions e.g. failure to allocate memory.

Example
using namespace BOOST_AFIO_V2_NAMESPACE;
using BOOST_AFIO_V2_NAMESPACE::rmdir;
std::shared_ptr<boost::afio::dispatcher> dispatcher =
boost::afio::make_dispatcher().get();
current_dispatcher_guard h(dispatcher);

// Free function
try
{
  // Schedule creating a directory called testdir
  auto mkdir(async_dir("testdir", boost::afio::file_flags::create));
  // Schedule creating a file called testfile in testdir only when testdir has been
  // created
  auto mkfile(async_file(mkdir, "testfile", boost::afio::file_flags::create));
  // Schedule creating a symbolic link called linktodir to the item referred to by
  // the precondition
  // i.e. testdir. Note that on Windows you can only symbolic link directories.
  auto mklink(
  async_symlink(mkdir, "linktodir", mkdir, boost::afio::file_flags::create));

  // Schedule deleting the symbolic link only after when it has been created
  auto rmlink(async_rmsymlink(mklink));
  // Schedule deleting the file only after when it has been created
  auto rmfile(async_close(async_rmfile(mkfile)));
  // Schedule waiting until both the preceding operations have finished
  auto barrier(dispatcher->barrier({rmlink, rmfile}));
  // Schedule deleting the directory only after the barrier completes
  auto rmdir(async_rmdir(depends(barrier.front(), mkdir)));
  // Check ops for errors
  boost::afio::when_all_p(mkdir, mkfile, mklink, rmlink, rmfile, rmdir).wait();
}
catch(...)
{
  std::cerr << boost::current_exception_diagnostic_information(true) << std::endl;
  throw;
}

// Batch
try
{
  // Schedule creating a directory called testdir
  auto mkdir(
  dispatcher->dir(std::vector<boost::afio::path_req>(
                  1, boost::afio::path_req(
                     "testdir", boost::afio::file_flags::create))).front());
  // Schedule creating a file called testfile in testdir only when testdir has been
  // created
  auto mkfile(dispatcher->file(std::vector<boost::afio::path_req>(
                               1, boost::afio::path_req::relative(
                                  mkdir, "testfile",
                                  boost::afio::file_flags::create))).front());
  // Schedule creating a symbolic link called linktodir to the item referred to by
  // the precondition
  // i.e. testdir. Note that on Windows you can only symbolic link directories.
  // Note that creating
  // symlinks must *always* be as an absolute path, as that is how they are stored.
  auto mklink(dispatcher->symlink(std::vector<boost::afio::path_req>(
                                  1, boost::afio::path_req::absolute(
                                     mkdir, "testdir/linktodir",
                                     boost::afio::file_flags::create))).front());

  // Schedule deleting the symbolic link only after when it has been created
  auto rmlink(dispatcher->close(std::vector<future<>>(
                                1, dispatcher->rmsymlink(mklink))).front());
  // Schedule deleting the file only after when it has been created
  auto rmfile(
  dispatcher->close(std::vector<future<>>(1, dispatcher->rmfile(mkfile))).front());
  // Schedule waiting until both the preceding operations have finished
  auto barrier(dispatcher->barrier({rmlink, rmfile}));
  // Schedule deleting the directory only after the barrier completes
  auto rmdir(
  dispatcher->rmdir(std::vector<path_req>(
                    1, dispatcher->depends(barrier.front(), mkdir))).front());
  // Check ops for errors
  boost::afio::when_all_p(mkdir, mkfile, mklink, rmlink, rmfile, rmdir).wait();
}
catch(...)
{
  std::cerr << boost::current_exception_diagnostic_information(true) << std::endl;
  throw;
}


PrevUpHomeNext