bsd/man/man2/chdir.2

   1 .\"     $NetBSD: chdir.2,v 1.7 1995/02/27 12:32:00 cgd Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)chdir.2     8.2 (Berkeley) 12/11/93
  35 .\"
  36 .Dd December 11, 1993
  37 .Dt CHDIR 2
  38 .Os BSD 4
  39 .Sh NAME
  40 .Nm chdir ,
  41 .Nm fchdir
  42 .Nd change current working directory
  43 .Sh SYNOPSIS
  44 .Fd #include <unistd.h>
  45 .Ft int
  46 .Fo chdir
  47 .Fa "const char *path"
  48 .Fc
  49 .Ft int
  50 .Fo fchdir
  51 .Fa "int fildes"
  52 .Fc
  53 .Sh DESCRIPTION
  54 The
  55 .Fa path
  56 argument points to the pathname of a directory.
  57 The
  58 .Fn chdir
  59 function
  60 causes the named directory
  61 to become the current working directory, that is,
  62 the starting point for path searches of pathnames not beginning with
  63 a slash,
  64 .Ql / .
  65 .Pp
  66 The
  67 .Fn fchdir
  68 function
  69 causes the directory referenced by
  70 .Fa fildes
  71 to become the current working directory,
  72 the starting point for path searches of pathnames not beginning with
  73 a slash,
  74 .Ql / .
  75 .Pp
  76 In order for a directory to become the current directory,
  77 a process must have execute (search) access to the directory.
  78 .Sh RETURN VALUES
  79 Upon successful completion, a value of 0 is returned.
  80 Otherwise, a value of -1 is returned and
  81 .Va errno
  82 is set to indicate
  83 the error.
  84 .Sh ERRORS
  85 The
  86 .Fn Chdir
  87 system call will fail
  88 and the current working directory will be unchanged
  89 if one or more of the following are true:
  90 .Bl -tag -width Er
  91 .\" ==========
  92 .It Bq Er EACCES
  93 Search permission is denied for any component of
  94 the path name.
  95 .\" ==========
  96 .It Bq Er EFAULT
  97 .Fa Path
  98 points outside the process's allocated address space.
  99 .\" ==========
 100 .It Bq Er EIO
 101 An I/O error occurred while reading from or writing to the file system.
 102 .\" ==========
 103 .It Bq Er ELOOP
 104 Too many symbolic links were encountered in translating the pathname.
 105 This is taken to be indicative of a looping symbolic link.
 106 .\" ==========
 107 .It Bq Er ENAMETOOLONG
 108 A component of a pathname exceeded
 109 .Dv {NAME_MAX}
 110 characters, or an entire path name exceeded
 111 .Dv {PATH_MAX}
 112 characters.
 113 .\" ==========
 114 .It Bq Er ENOENT
 115 The named directory does not exist.
 116 .\" ==========
 117 .It Bq Er ENOTDIR
 118 A component of the path prefix is not a directory.
 119 .El
 120 .Pp
 121 .Fn Fchdir
 122 will fail and the current working directory will be unchanged if
 123 one or more of the following are true:
 124 .Bl -tag -width Er
 125 .\" ==========
 126 .It Bq Er EACCES
 127 Search permission is denied for the directory referenced by the
 128 file descriptor.
 129 .\" ==========
 130 .It Bq Er EBADF
 131 The argument
 132 .Fa fildes
 133 is not a valid file descriptor.
 134 .\" ==========
 135 .It Bq Er EINTR
 136 .Fn Fchdir was interrupted by a signal.
 137 .\" ==========
 138 .It Bq Er EIO
 139 An I/O error occurred while reading from or writing to the file system.
 140 .\" ==========
 141 .It Bq Er ENOTDIR
 142 The file descriptor does not reference a directory.
 143 .El
 144 .Sh SEE ALSO
 145 .Xr chroot 2
 146 .Sh STANDARDS
 147 The
 148 .Fn chdir
 149 is expected to conform to
 150 .St -p1003.1-88 .
 151 .Sh HISTORY
 152 The
 153 .Fn fchdir
 154 function call
 155 appeared in
 156 .Bx 4.2 .