Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
filelib(3)		   Erlang Module Definition		    filelib(3)

NAME
       filelib - File utilities, such as wildcard matching of filenames.

DESCRIPTION
       This module contains utilities on a higher level	than the file module.

       This  module  does  not	support	 "raw" filenames (that is, files whose
       names do	not comply with	the expected encoding).	Such files are ignored
       by the functions	in this	module.

       For more	information about raw filenames, see the file module.

   Note:
       Functionality in	this module generally assumes valid input and does not
       necessarily fail	on input that does not use a valid encoding,  but  may
       instead very likely produce invalid output.

       File  operations	 used  to  accept filenames containing null characters
       (integer	value zero). This caused the name to be	truncated and in  some
       cases  arguments	to primitive operations	to be mixed up.	Filenames con-
       taining null characters inside the filename are now rejected  and  will
       cause primitive file operations to fail.

   Warning:
       Currently  null	characters at the end of the filename will be accepted
       by primitive file operations. Such filenames are	 however  still	 docu-
       mented  as  invalid.  The implementation	will also change in the	future
       and reject such filenames.

DATA TYPES
       filename() = file:name()

       dirname() = filename()

       dirname_all() = filename_all()

       filename_all() =	file:name_all()

       find_file_rule()	=
	   {ObjDirSuffix :: string(), SrcDirSuffix :: string()}

       find_source_rule() =
	   {ObjExtension :: string(),
	    SrcExtension :: string(),
	    [find_file_rule()]}

EXPORTS
       ensure_dir(Name)	-> ok |	{error,	Reason}

	      Types:

		 Name =	filename_all() | dirname_all()
		 Reason	= file:posix()

	      Ensures that all parent directories for the  specified  file  or
	      directory	name Name exist, trying	to create them if necessary.

	      Returns  ok  if  all  parent directories already exist or	can be
	      created. Returns {error, Reason} if some parent  directory  does
	      not exist	and cannot be created.

       file_size(Filename) -> integer()	>= 0

	      Types:

		 Filename = filename_all()

	      Returns the size of the specified	file.

       fold_files(Dir, RegExp, Recursive, Fun, AccIn) -> AccOut

	      Types:

		 Dir = dirname()
		 RegExp	= string()
		 Recursive = boolean()
		 Fun = fun((F :: file:filename(), AccIn) -> AccOut)
		 AccIn = AccOut	= term()

	      Folds  function  Fun over	all (regular) files F in directory Dir
	      that match the regular expression	RegExp (for a  description  of
	      the  allowed  regular expressions, see the re module). If	Recur-
	      sive is true, all	subdirectories to Dir are processed. The regu-
	      lar expression matching is only done on the filename without the
	      directory	part.

	      If Unicode filename translation is in effect and the file	system
	      is  transparent, filenames that cannot be	interpreted as Unicode
	      can be encountered, in which case	the fun() must be prepared  to
	      handle raw filenames (that is, binaries).	If the regular expres-
	      sion contains codepoints > 255, it does not match	filenames that
	      do  not conform to the expected character	encoding (that is, are
	      not encoded in valid UTF-8).

	      For more information about raw filenames,	see the	file module.

       is_dir(Name) -> boolean()

	      Types:

		 Name =	filename_all() | dirname_all()

	      Returns true if Name refers to a directory, otherwise false.

       is_file(Name) ->	boolean()

	      Types:

		 Name =	filename_all() | dirname_all()

	      Returns true if Name refers to a file or a directory,  otherwise
	      false.

       is_regular(Name)	-> boolean()

	      Types:

		 Name =	filename_all()

	      Returns  true  if	 Name  refers  to  a (regular) file, otherwise
	      false.

       last_modified(Name) -> file:date_time() | 0

	      Types:

		 Name =	filename_all() | dirname_all()

	      Returns the date and time	the specified file  or	directory  was
	      last modified, or	0 if the file does not exist.

       wildcard(Wildcard) -> [file:filename()]

	      Types:

		 Wildcard = filename() | dirname()

	      Returns  a  list	of  all	 files	that match Unix-style wildcard
	      string Wildcard.

	      The wildcard string looks	like an	ordinary filename, except that
	      the following "wildcard characters" are interpreted in a special
	      way:

		?:
		  Matches one character.

		*:
		  Matches any number of	characters up to the end of the	 file-
		  name,	the next dot, or the next slash.

		**:
		  Two  adjacent	* used as a single pattern match all files and
		  zero or more directories and subdirectories.

		[Character1,Character2,...]:
		  Matches any of the characters	listed.	Two  characters	 sepa-
		  rated	 by a hyphen match a range of characters. Example: [A-
		  Z] matches any uppercase letter.

		{Item,...}:
		  Alternation. Matches one of the alternatives.

	      Other characters represent themselves. Only filenames that  have
	      exactly  the same	character in the same position match. Matching
	      is case-sensitive, for example, "a" does not match "A".

	      Directory	separators must	always be written as /,	even  on  Win-
	      dows.

	      A	character preceded by \	loses its special meaning. Note	that \
	      must be written as \\ in a string	literal. For  example,	"\\?*"
	      will match any filename starting with ?.

	      Notice  that  multiple  "*"  characters  are allowed (as in Unix
	      wildcards, but opposed to	Windows/DOS wildcards).

	      Examples:

	      The following examples assume that the current directory is  the
	      top of an	Erlang/OTP installation.

	      To  find	all .beam files	in all applications, use the following
	      line:

	      filelib:wildcard("lib/*/ebin/*.beam").

	      To find .erl or .hrl in all applications	src  directories,  use
	      either of	the following lines:

	      filelib:wildcard("lib/*/src/*.?rl")

	      filelib:wildcard("lib/*/src/*.{erl,hrl}")

	      To find all .hrl files in	src or include directories:

	      filelib:wildcard("lib/*/{src,include}/*.hrl").

	      To find all .erl or .hrl files in	either src or include directo-
	      ries:

	      filelib:wildcard("lib/*/{src,include}/*.{erl,hrl}")

	      To find all .erl or .hrl files in	any subdirectory:

	      filelib:wildcard("lib/**/*.{erl,hrl}")

       wildcard(Wildcard, Cwd) -> [file:filename()]

	      Types:

		 Wildcard = filename() | dirname()
		 Cwd = dirname()

	      Same as wildcard/1, except that Cwd is used instead of the work-
	      ing directory.

       find_file(Filename :: filename(), Dir ::	filename()) ->
		    {ok, filename()} | {error, not_found}

       find_file(Filename :: filename(),
		 Dir ::	filename(),
		 Rules :: [find_file_rule()]) ->
		    {ok, filename()} | {error, not_found}

	      Looks  for  a file of the	given name by applying suffix rules to
	      the given	directory path.	For example, a	rule  {"ebin",	"src"}
	      means  that  if  the directory path ends with "ebin", the	corre-
	      sponding path ending in "src" should be searched.

	      If Rules is left out or is an empty  list,  the  default	system
	      rules  are  used.	 See  also  the	 Kernel	 application parameter
	      source_search_rules.

       find_source(FilePath :: filename()) ->
		      {ok, filename()} | {error, not_found}

	      Equivalent  to  find_source(Base,	 Dir),	where  Dir  is	 file-
	      name:dirname(FilePath) and Base is filename:basename(FilePath).

       find_source(Filename :: filename(), Dir :: filename()) ->
		      {ok, filename()} | {error, not_found}

       find_source(Filename :: filename(),
		   Dir :: filename(),
		   Rules :: [find_source_rule()]) ->
		      {ok, filename()} | {error, not_found}

	      Applies  file  extension	specific rules to find the source file
	      for a given object file relative to the  object  directory.  For
	      example,	for  a file with the extension .beam, the default rule
	      is to look for a file with a corresponding extension .erl	by re-
	      placing  the  suffix  "ebin"  of	the object directory path with
	      "src" or "src/*".	The file search	is done	 through  find_file/3.
	      The  directory  of  the  object  file is always tried before any
	      other directory specified	by the rules.

	      If Rules is left out or is an empty  list,  the  default	system
	      rules  are  used.	 See  also  the	 Kernel	 application parameter
	      source_search_rules.

Ericsson AB			  stdlib 3.8			    filelib(3)

NAME | DESCRIPTION | DATA TYPES | EXPORTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=filelib&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help