cd man page on Archlinux

Man page or keyword search:  
man Server   11224 pages
apropos Keyword Search (all sections)
Output format
Archlinux logo
[printable version]

CD(1P)			   POSIX Programmer's Manual			CD(1P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the	 corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.

NAME
       cd — change the working directory

SYNOPSIS
       cd [−L|−P] [directory]

       cdDESCRIPTION
       The cd utility shall change the working directory of the current	 shell
       execution  environment  (see Section 2.12, Shell Execution Environment)
       by executing the following steps in sequence. (In the following	steps,
       the  symbol  curpath  represents an intermediate value used to simplify
       the description of the algorithm used by cd.  There is  no  requirement
       that curpath be made visible to the application.)

	1. If  no directory operand is given and the HOME environment variable
	   is empty or undefined,  the	default	 behavior  is  implementation-
	   defined and no further steps shall be taken.

	2. If  no directory operand is given and the HOME environment variable
	   is set to a non-empty value, the cd utility shall behave as if  the
	   directory  named  in the HOME environment variable was specified as
	   the directory operand.

	3. If the directory operand begins with a <slash> character, set  cur‐
	   path to the operand and proceed to step 7.

	4. If  the first component of the directory operand is dot or dot-dot,
	   proceed to step 6.

	5. Starting with the first pathname in the <colon>-separated pathnames
	   of  CDPATH  (see the ENVIRONMENT VARIABLES section) if the pathname
	   is non-null, test if the concatenation of that pathname, a  <slash>
	   character  if  that	pathname did not end with a <slash> character,
	   and the directory operand names a directory.	 If  the  pathname  is
	   null,  test	if  the concatenation of dot, a <slash> character, and
	   the operand names a directory. In either  case,  if	the  resulting
	   string  names an existing directory, set curpath to that string and
	   proceed to step 7. Otherwise, repeat this step with the next	 path‐
	   name in CDPATH until all pathnames have been tested.

	6. Set curpath to the directory operand.

	7. If  the −P option is in effect, proceed to step 10. If curpath does
	   not begin with a <slash>  character,	 set  curpath  to  the	string
	   formed  by the concatenation of the value of PWD, a <slash> charac‐
	   ter if the value of PWD did not end with a <slash>  character,  and
	   curpath.

	8. The curpath value shall then be converted to canonical form as fol‐
	   lows,  considering  each  component	from  beginning	 to  end,   in
	   sequence:

	    a. Dot  components	and  any <slash> characters that separate them
	       from the next component shall be deleted.

	    b. For each dot-dot component, if there is a  preceding  component
	       and it is neither root nor dot-dot, then:

		i.  If	the preceding component does not refer (in the context
		    of pathname resolution with symbolic links followed) to  a
		    directory,	then the cd utility shall display an appropri‐
		    ate error message and no further steps shall be taken.

	       ii.  The preceding component, all <slash> characters separating
		    the	 preceding  component  from  dot-dot, dot-dot, and all
		    <slash> characters separating dot-dot from	the  following
		    component (if any) shall be deleted.

	    c. An  implementation may further simplify curpath by removing any
	       trailing <slash> characters that are not also  leading  <slash>
	       characters,  replacing multiple non-leading consecutive <slash>
	       characters with a single <slash>, and replacing three  or  more
	       leading	<slash>	 characters  with  a single <slash>.  If, as a
	       result of this canonicalization, the curpath variable is	 null,
	       no further steps shall be taken.

	9. If curpath is longer than {PATH_MAX} bytes (including the terminat‐
	   ing null) and the directory operand was not longer than  {PATH_MAX}
	   bytes  (including the terminating null), then curpath shall be con‐
	   verted from an absolute pathname to an equivalent relative pathname
	   if possible. This conversion shall always be considered possible if
	   the value of PWD, with a trailing <slash>  added  if	 it  does  not
	   already  have  one, is an initial substring of curpath.  Whether or
	   not it is considered possible under other circumstances is unspeci‐
	   fied.  Implementations may also apply this conversion if curpath is
	   not longer than {PATH_MAX}  bytes  or  the  directory  operand  was
	   longer than {PATH_MAX} bytes.

       10. The cd utility shall then perform actions equivalent to the chdir()
	   function called with curpath as the path argument. If these actions
	   fail	 for  any  reason, the cd utility shall display an appropriate
	   error message and the remainder of this step shall not be executed.
	   If  the  −P	option	is not in effect, the PWD environment variable
	   shall be set to the value that curpath  had	on  entry  to  step  9
	   (i.e.,  before conversion to a relative pathname). If the −P option
	   is in effect, the PWD environment variable  shall  be  set  to  the
	   string  that	 would	be output by pwd −P.  If there is insufficient
	   permission on the new directory, or on any parent  of  that	direc‐
	   tory,  to determine the current working directory, the value of the
	   PWD environment variable is unspecified.

       If, during the execution of the above steps, the PWD environment	 vari‐
       able  is	 set, the OLDPWD environment variable shall also be set to the
       value of the old working directory (that is the current working	direc‐
       tory immediately prior to the call to cd).

OPTIONS
       The  cd	utility	 shall	conform	 to  the  Base	Definitions  volume of
       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.

       The following options shall be supported by the implementation:

       −L	 Handle the operand dot-dot logically;	symbolic  link	compo‐
		 nents	shall  not  be	resolved before dot-dot components are
		 processed (see steps 8.  and 9. in the DESCRIPTION).

       −P	 Handle the operand dot-dot physically; symbolic  link	compo‐
		 nents	shall  be  resolved before dot-dot components are pro‐
		 cessed (see step 7. in the DESCRIPTION).

       If both −L and −P options are specified,	 the  last  of	these  options
       shall  be  used	and all others ignored. If neither −L nor −P is speci‐
       fied, the operand shall be handled dot-dot logically; see the  DESCRIP‐
       TION.

OPERANDS
       The following operands shall be supported:

       directory An  absolute or relative pathname of the directory that shall
		 become the new working directory.  The	 interpretation	 of  a
		 relative  pathname  by	 cd  depends  on the −L option and the
		 CDPATH and PWD environment  variables.	 If  directory	is  an
		 empty string, the results are unspecified.

       −	 When a <hyphen> is used as the operand, this shall be equiva‐
		 lent to the command:

		     cd "$OLDPWD" && pwd

		 which changes to the  previous	 working  directory  and  then
		 writes its name.

STDIN
       Not used.

INPUT FILES
       None.

ENVIRONMENT VARIABLES
       The following environment variables shall affect the execution of cd:

       CDPATH	 A  <colon>-separated list of pathnames that refer to directo‐
		 ries. The cd utility shall use this list in  its  attempt  to
		 change	 the  directory,  as  described in the DESCRIPTION. An
		 empty string in place of a directory pathname represents  the
		 current  directory. If CDPATH is not set, it shall be treated
		 as if it were an empty string.

       HOME	 The name of the directory, used when no directory operand  is
		 specified.

       LANG	 Provide  a  default  value for the internationalization vari‐
		 ables that are unset or null. (See the Base Definitions  vol‐
		 ume  of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
		 ables for the precedence  of  internationalization  variables
		 used to determine the values of locale categories.)

       LC_ALL	 If  set  to  a non-empty string value, override the values of
		 all the other internationalization variables.

       LC_CTYPE	 Determine the locale for the interpretation of	 sequences  of
		 bytes of text data as characters (for example, single-byte as
		 opposed to multi-byte characters in arguments).

       LC_MESSAGES
		 Determine the locale that should be used to affect the format
		 and  contents	of  diagnostic	messages  written  to standard
		 error.

       NLSPATH	 Determine the location of message catalogs for the processing
		 of LC_MESSAGES.

       OLDPWD	 A pathname of the previous working directory, used by cd −.

       PWD	 This  variable	 shall be set as specified in the DESCRIPTION.
		 If an application sets or unsets the value of PWD, the behav‐
		 ior of cd is unspecified.

ASYNCHRONOUS EVENTS
       Default.

STDOUT
       If  a non-empty directory name from CDPATH is used, or if cd − is used,
       an absolute pathname of the new working directory shall be  written  to
       the standard output as follows:

	   "%s\n", <new directory>

       Otherwise, there shall be no output.

STDERR
       The standard error shall be used only for diagnostic messages.

OUTPUT FILES
       None.

EXTENDED DESCRIPTION
       None.

EXIT STATUS
       The following exit values shall be returned:

	0    The directory was successfully changed.

       >0    An error occurred.

CONSEQUENCES OF ERRORS
       The working directory shall remain unchanged.

       The following sections are informative.

APPLICATION USAGE
       Since  cd affects the current shell execution environment, it is always
       provided as a shell regular built-in. If it is called in a subshell  or
       separate utility execution environment, such as one of the following:

	   (cd /tmp)
	   nohup cd
	   find . −exec cd {} \;

       it does not affect the working directory of the caller's environment.

       The user must have execute (search) permission in directory in order to
       change to it.

EXAMPLES
       The following template can be used to perform processing in the	direc‐
       tory  specified by location and end up in the current working directory
       in use before the first cd command was issued:

	   cd location
	   if [ $? -ne 0 ]
	   then
	       print error message
	       exit 1
	   fi
	   ... do whatever is desired as long as the OLDPWD environment variable
	       is not modified
	   cd -

RATIONALE
       The use of the CDPATH was introduced in the System V shell. Its use  is
       analogous to the use of the PATH variable in the shell. The BSD C shell
       used a shell parameter cdpath for this purpose.

       A common extension when HOME is undefined is to get the login directory
       from  the  user	database for the invoking user. This does not occur on
       System V implementations.

       Some historical shells, such as the  KornShell,	took  special  actions
       when  the  directory  name contained a dot-dot component, selecting the
       logical parent of the directory, rather than the actual	parent	direc‐
       tory;  that  is,	 it moved up one level toward the '/' in the pathname,
       remembering what the user typed, rather than performing the  equivalent
       of:

	   chdir("..");

       In  such	 a shell, the following commands would not necessarily produce
       equivalent output for all directories:

	   cd .. && ls	    ls ..

       This behavior is now the default. It is not consistent with the defini‐
       tion of dot-dot in most historical practice; that is, while this behav‐
       ior has been optionally available in the KornShell, other  shells  have
       historically  not supported this functionality. The logical pathname is
       stored in the PWD environment variable when the	cd  utility  completes
       and  this  value	 is used to construct the next directory name if cd is
       invoked with the −L option.

FUTURE DIRECTIONS
       None.

SEE ALSO
       Section 2.12, Shell Execution Environment, pwd

       The Base Definitions volume of  POSIX.1‐2008,  Chapter  8,  Environment
       Variables, Section 12.2, Utility Syntax Guidelines

       The System Interfaces volume of POSIX.1‐2008, chdir()

COPYRIGHT
       Portions	 of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       --  Portable  Operating	System	Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
       cal  and	 Electronics  Engineers,  Inc  and  The	 Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum	 1  applied.)  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the	referee document. The original Standard can be obtained online
       at http://www.unix.org/online.html .

       Any typographical or formatting errors that appear  in  this  page  are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors,	 see  https://www.ker‐
       nel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group		     2013				CD(1P)
[top]

List of man pages available for Archlinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net