usr/src/man/man3c/getcwd.3c

   1 '\" te
   2 .\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
   5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   6 .\" http://www.opengroup.org/bookstore/.
   7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions 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.opengroup.org/unix/online.html.
   8 .\"  This notice shall appear on any product containing this material.
   9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
  10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
  11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  12 .TH GETCWD 3C "Oct 18, 2004"
  13 .SH NAME
  14 getcwd \- get pathname of current working directory
  15 .SH SYNOPSIS
  16 .LP
  17 .nf
  18 #include <unistd.h>
  19
  20 \fBchar *\fR\fBgetcwd\fR(\fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
  21 .fi
  22
  23 .SH DESCRIPTION
  24 .sp
  25 .LP
  26 The \fBgetcwd()\fR function places an absolute pathname of the current working
  27 directory in the array pointed to by \fIbuf\fR, and returns \fIbuf\fR. The
  28 pathname copied to the array contains no components that are symbolic links.
  29 The \fIsize\fR argument is the size in bytes of the character array pointed to
  30 by \fIbuf\fR and must be at least one greater than the length of the pathname
  31 to be returned.
  32 .sp
  33 .LP
  34 If \fIbuf\fR is not a null pointer, the pathname is stored in the space pointed
  35 to by \fIbuf\fR.
  36 .sp
  37 .LP
  38 If \fIbuf\fR is a null pointer, \fBgetcwd()\fR obtains \fIsize\fR bytes of
  39 space using \fBmalloc\fR(3C). The pointer returned by \fBgetcwd()\fR can be
  40 used as the argument in a subsequent call to \fBfree()\fR.
  41 .SH RETURN VALUES
  42 .sp
  43 .LP
  44 Upon successful completion, \fBgetcwd()\fR returns the \fIbuf\fR argument. If
  45 \fIbuf\fR is an invalid destination buffer address, \fINULL\fR is returned and
  46 \fBerrno\fR is set to \fBEFAULT\fR. Otherwise, a null pointer is returned and
  47 \fBerrno\fR is set to indicate the error.
  48 .SH ERRORS
  49 .sp
  50 .LP
  51 The \fBgetcwd()\fR function will fail if:
  52 .sp
  53 .ne 2
  54 .na
  55 \fB\fBEFAULT\fR\fR
  56 .ad
  57 .RS 10n
  58 The \fIbuf\fR argument is an invalid destination buffer address.
  59 .RE
  60
  61 .sp
  62 .ne 2
  63 .na
  64 \fB\fBEINVAL\fR\fR
  65 .ad
  66 .RS 10n
  67 The \fIsize\fR argument is equal to 0.
  68 .RE
  69
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fBERANGE\fR\fR
  74 .ad
  75 .RS 10n
  76 The \fIsize\fR argument is greater than 0 and less than the length of the
  77 pathname plus 1.
  78 .RE
  79
  80 .sp
  81 .LP
  82 The \fBgetcwd()\fR function may fail if:
  83 .sp
  84 .ne 2
  85 .na
  86 \fB\fBEACCES\fR\fR
  87 .ad
  88 .RS 10n
  89 A parent directory cannot be read to get its name.
  90 .RE
  91
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fBENOMEM\fR\fR
  96 .ad
  97 .RS 10n
  98 Insufficient storage space is available.
  99 .RE
 100
 101 .SH EXAMPLES
 102 .LP
 103 \fBExample 1 \fRDetermine the absolute pathname of the current working
 104 directory.
 105 .sp
 106 .LP
 107 The following example returns a pointer to an array that holds the absolute
 108 pathname of the current working directory. The pointer is returned in the
 109 \fIptr\fR variable, which points to the \fIbuf\fR array where the pathname is
 110 stored.
 111
 112 .sp
 113 .in +2
 114 .nf
 115 #include <stdlib.h>
 116 #include <unistd.h>
 117 \&...
 118 long size;
 119 char *buf;
 120 char *ptr;
 121 size = pathconf(".", _PC_PATH_MAX);
 122 if ((buf = (char *)malloc((size_t)size)) != NULL)
 123        ptr = getcwd(buf, (size_t)size);
 124 \&...
 125 .fi
 126 .in -2
 127
 128 .LP
 129 \fBExample 2 \fRPrint the current working directory.
 130 .sp
 131 .LP
 132 The following example prints the current working directory.
 133
 134 .sp
 135 .in +2
 136 .nf
 137 #include <unistd.h>
 138 #include <stdio.h>
 139
 140 main(\|)
 141 {
 142     char *cwd;
 143     if ((cwd = getcwd(NULL, 64)) == NULL) {
 144         perror("pwd");
 145         exit(2);
 146     }
 147     (void)printf("%s\en", cwd);
 148     free(cwd); /* free memory allocated by getcwd() */
 149     return(0);
 150 }
 151 .fi
 152 .in -2
 153
 154 .SH USAGE
 155 .sp
 156 .LP
 157 Applications should exercise care when using \fBchdir\fR(2) in conjunction with
 158 \fBgetcwd()\fR. The current working directory is global to all threads within a
 159 process. If more than one thread calls \fBchdir()\fR to change the working
 160 directory, a subsequent call to \fBgetcwd()\fR could produce unexpected
 161 results.
 162 .SH ATTRIBUTES
 163 .sp
 164 .LP
 165 See \fBattributes\fR(5) for descriptions of the following attributes:
 166 .sp
 167
 168 .sp
 169 .TS
 170 box;
 171 c | c
 172 l | l .
 173 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 174 _
 175 Interface Stability     Standard
 176 _
 177 MT-Level        MT-Safe
 178 .TE
 179
 180 .SH SEE ALSO
 181 .sp
 182 .LP
 183 \fBchdir\fR(2), \fBmalloc\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)