ОБЗОР

#include <unistd.h>

---

char *getcwd(char *buf, size_t size);

---

char *getwd(char *buf);

---

char *get_current_dir_name(void);

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

get_current_dir_name():

_GNU_SOURCE

getwd():

Начиная с glibc 2.12:

_BSD_SOURCE ||
    (_XOPEN_SOURCE >= 500 ||
        _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
    !(_POSIX_C_SOURCE >= 200809L || _XOPEN_SOURCE >= 700)

До glibc 2.12: _BSD_SOURCE || _XOPEN_SOURCE >= 500 || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED

ОПИСАНИЕ

Данные функции возвращают строку (с null в конце), содержащую абсолютный путь текущего рабочего каталога вызывающего процесса. Путь возвращается как результат функции или в аргументе buf, если он есть.

Если текущий каталог расположен не ниже корневого каталога текущего процесса (например, процесс задал новый корневой каталог файловой системы с помощью chroot(2) и не сменил свой текущий каталог на новый корень), то начиная с Linux 2.6.36, возвращаемый путь будет начинаться со строки «(unreachable)». Такое поведение также можно увидеть, если непривилегированный пользователь изменил текущий каталог в другом пространстве имён mount. При работе с путями из недоверительных источников вызывающий этих функций должен проверять начинается ли возвращённый путь с «/» или «(», чтобы избежать неверного понимания недостижимого пути как относительного пути.

Функция getcwd() копирует абсолютный путь текущего рабочего каталога в массив, на который указывает buf, имеющий длину size.

Если длина абсолютного пути, включая конечный байт null, превышает size байт, то возвращается NULL, а errno принимает значение ERANGE; приложение должно проверить, возникла эта ошибка или нет и, если необходимо, выделить буфер большего размера.

Согласно расширению стандарта POSIX.1-2001 в glibc предусмотрено следующее: если buf равно NULL, то при вызове getcwd() буфер выделяется динамически с помощью функции malloc(3). В этом случае выделенный буфер имеет размер size; если size равно нулю, то выделяется buf необходимого размера. Вызывающий после использования должен освободить выделенный буфер с помощью free(3).

Функция get_current_dir_name() выделит с помощью malloc(3) массив, достаточно большой для помещения в него абсолютного пути имени текущего каталога. Если существует и имеет правильное значение переменная окружения PWD, то будет возвращено её значение. Вызывающий после использования должен освободить выделенный буфер с помощью free(3).

Функция getwd() не выделяет память с помощью malloc(3). Аргумент buf должен быть указателем на массив длиной не менее PATH_MAX байтов. Если длина абсолютного пути текущего рабочего каталога, включая конечный байт null, превышает PATH_MAX байт, то возвращается NULL и errno присваивается значение ENAMETOOLONG (заметим, что в некоторых системах PATH_MAX может не являться константой времени компиляции; более того, её значение может зависеть от файловой системы, смотрите pathconf(3)). Для переносимости и безопасности использование getwd() не рекомендуется.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

При успешном выполнении эти функции возвращают указатель на строку, содержащую пути текущего рабочего каталога. У getcwd() и getwd() это значение совпадает с buf.

При ошибках эти функции возвращают NULL и в errno помещают причину ошибки. Содержимое массива buf в этом случае не определено.

АТРИБУТЫ

Описание терминов данного раздела смотрите в attributes(7).

Интерфейс	Атрибут	Значение
getcwd(), getwd()	безвредность в нитях	безвредно (MT-Safe)
get_current_dir_name()	безвредность в нитях	безвредно (MT-Safe env)

СООТВЕТСТВИЕ СТАНДАРТАМ

Функция getcwd() соответствует POSIX.1-2001. Однако заметим, что в POSIX.1-2001 не описано поведение getcwd(), если buf равно NULL.

Функция getwd() описана в POSIX.1-2001, но помечена как УСТАРЕВШАЯ. В POSIX.1-2008 getwd() удалена. Вместо неё используйте getcwd(). В POSIX.1-2001 не определены ошибки, возвращаемые getwd().

Функция get_current_dir_name() является расширением GNU.

ЗАМЕЧАНИЯ

В Linux, функция getcwd() является системным вызовом (начиная с 2.1.92). В более старых системах она опрашивает /proc/self/cwd. Если в системе отсутствует системный вызов и файловая система proc, то задействуется обобщённая реализация. Только в этом случает данные вызовы в Linux могут завершиться с ошибкой EACCES.

Данные функции часто используются для сохранения расположения текущего рабочего каталога с целью возврата в него позднее. Открытие текущего каталога («.») и вызов fchdir(2) для возврата, обычно, более быстрая и надёжная альтернатива при наличии достаточного количества файловых дескрипторов, особенно на платформах, отличных от Linux.