Commit | Line | Data |
---|---|---|
e2462278 KB |
1 | .\" Copyright (c) 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
861bcf00 | 3 | .\" |
e2462278 KB |
4 | .\" %sccs.include.redist.man% |
5 | .\" | |
6 | .\" @(#)getcwd.3 6.3 (Berkeley) %G% | |
861bcf00 | 7 | .\" |
9594a5eb | 8 | .TH GETWD 3 "" |
861bcf00 KM |
9 | .UC 5 |
10 | .SH NAME | |
e2462278 | 11 | getwd \- get working directory pathname |
861bcf00 KM |
12 | .SH SYNOPSIS |
13 | .nf | |
e2462278 KB |
14 | .ft B |
15 | char *getcwd(char *buf, size_t size); | |
16 | char *getwd(char *buf); | |
17 | .ft R | |
861bcf00 KM |
18 | .fi |
19 | .SH DESCRIPTION | |
e2462278 KB |
20 | The |
21 | .I getcwd | |
22 | function copies the absolute pathname of the current working directory | |
23 | into the memory referenced by | |
24 | .I buf | |
25 | and returns a pointer to | |
26 | .IR buf . | |
27 | The | |
28 | .I size | |
29 | argument is the size, in bytes, of the array referenced by | |
30 | .IR buf . | |
31 | .PP | |
32 | If | |
33 | .I buf | |
34 | is NULL, space is allocated as necessary to store the pathname. | |
35 | This space may later be | |
36 | .IR free 'd. | |
37 | .PP | |
38 | The function | |
39 | .I getwd | |
40 | is a compatibility routine which calls | |
41 | .I getcwd | |
42 | with its | |
43 | .I buf | |
44 | argument and a size of MAXPATHLEN (as defined in the include | |
45 | file <sys/param.h>). | |
46 | Obviously, | |
47 | .I buf | |
48 | should be at least MAXPATHLEN bytes in length. | |
49 | .PP | |
50 | These routines have traditionally been used by programs to save the | |
51 | name of a working directory for the purpose of returning to it. | |
52 | A much faster and less error-prone method of accomplishing this is to | |
53 | open the current directory (``.'') and use the | |
54 | .IR fchdir (2) | |
55 | function to return. | |
56 | .SH RETURN VALUES | |
57 | Upon successful completion, a pointer to the pathname is returned. | |
58 | Otherwise a NULL pointer is returned and | |
59 | .I errno | |
60 | is set to indicate the error. | |
61 | In addition, | |
62 | .I getwd | |
63 | copies the error message associated with | |
64 | .I errno | |
65 | into the memory referenced by | |
66 | .IR buf . | |
67 | .SH ERRORS | |
68 | .I Getcwd | |
69 | will fail if: | |
70 | .TP 15 | |
71 | [EACCESS] | |
72 | Read or search permission was denied for a component of the pathname. | |
73 | .TP 15 | |
74 | [EINVAL] | |
75 | The | |
76 | .I size | |
77 | argument is zero. | |
78 | .TP 15 | |
79 | [ENOENT] | |
80 | A component of the pathname no longer exists. | |
81 | .TP 15 | |
82 | [ENOMEM] | |
83 | Insufficient memory is available. | |
84 | .TP 15 | |
85 | [ERANGE] | |
86 | The | |
87 | .I size | |
88 | argument is greater than zero but smaller than the length of the pathname | |
89 | plus 1. | |
90 | .SH BUGS | |
861bcf00 | 91 | .I Getwd |
e2462278 KB |
92 | does not do sufficient error checking and is not able to return very |
93 | long, but valid, paths. | |
94 | It is provided for compatibility. | |
95 | .SH SEE ALSO | |
96 | chdir(2), fchdir(2), malloc(3), strerror(3) | |
97 | .SH STANDARDS | |
98 | .I Getcwd | |
99 | conforms to IEEE Std 1003.1-1988 (``POSIX''). | |
100 | The ability to specify a NULL pointer and have | |
101 | .I getcwd | |
102 | allocate memory as necessary is an extension. |