Пример страницы Руководства (секция 3)

Библиотечные функции перечислены в Секции 3.
(3C) означает что эта функция размещена в стандартной библиотеке Cи (в
/usr/ccs/lib/libc.a или в /usr/ccs/lib/libc.so).
ИМЯ  имя функции и краткое описание.
ИСПОЛЬЗОВАНИЕ  соответствующий include-файл и объявление функции
perror. Объявление говорит, что perror(3C) ничего не возвращает (void)
и требует один аргумент. Аргумент должен быть адресом символа, в
данном случае - адресом символьной строки.
ОПИСАНИЕ  работа функции. perror(3C) печатает текст, переданный в
качестве аргумента, затем двоеточие и пробел, затем сообщение об
ошибке по текущему значению errno и перевод строки. Описание сообщений
об ошибках можно найти на странице Руководства  INTRO(2) и в файле
<errno.h>.
Сообщение об ошибке может быть включено в отформатированную
пользователем строку при помощи strerror(3C). Эта функция возвращает
указатель на сообщение об ошибке по значению errno. Эта функция
использует внешнюю переменную errno как индекс во внешнем массиве,
называемом sys_errlist[]. Это массив указателей на различные сообщения
об ошибках, связанных со значением errno. Эти две переменные
описываются на странице STRERROR(3C).
Пример: printf("A %s caused the error\n", strerror(errno));
                ПРИМЕР СТРАНИЦЫ РУКОВОДСТВА (СЕКЦИЯ 3)
PERROR(3C)              UNIX System V               PERROR(3C)



ИМЯ

      perror - напечатать системное сообщение об ошибке

ИСПОЛЬЗОВАНИЕ

      #include <stdio.h>

      void perror(const char *s);

ОПИСАНИЕ

      perror  выводит   в  стандартный  вывод  диагностики  сообщение,
      описывающее последнюю  ошибку, обнаруженную при вызове системной
      или библиотечной функции. Сначала печатается строка параметра s,
      затем двоеточие и пробел, затем сообщение и перевод строки.

      ... Номер  ошибки берется  из внешней  переменной errno, которая
      устанавливается при  ошибочном, но  не  очищается  при  успешном
      системном вызове.

СМ. ТАКЖЕ

      intro(2), fmtmsg(3C), strerror(3C).

                Пример страницы Руководства (Секция 2)

ИМЯ  название системного вызова и однострочное описание
  ИСПОЛЬЗОВАНИЕ     необходимые  include-файлы.   time(2)   возвращает
                значение типа  time_t, представляющее время в секундах
                с 1  января 1970 года, 00:00:00 UTC. time требует один
                параметр, адрес  time_t. Тип time_t представляет собой
                typedef, определенный  в <sys/types.h>.  Если параметр
                ненулевой, возвращаемое значение также запоминается по
                адресу, заданному в качестве параметра.

ОПИСАНИЕ  указывает, что time(2) возвращает значение time_t,
соответствующее текущему времени, измеренному в секундах с 1 января
1970 года, 00:00:00 UTC.
                time(2) возвращает  -1 в  случае  неуспеха.  Некоторые
                системные   вызовы   могут   по   различным   причинам
                завершаться  неудачно.   Многие  страницы  Руководства
                перечисляют коды  ошибок, начинающиеся  с  буквы  'E',
                которые обозначают конкретную причину неуспеха.

  ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ  объясняет значения,  возвращаемые при  успехе
                или неуспехе.

СМ. ТАКЖЕ перечисляет функции или системные вызовы, имеющие отношение
к данному. stime(2) используется суперпользователем для установки
часов. ctime(3C) используется для преобразование значения time(2) и
будет обсуждаться вкратце.
                ПРИМЕР СТРАНИЦЫ РУКОВОДСТВА (СЕКЦИЯ 2)
TIME(2)                 UNIX System V               TIME(2)



ИМЯ

      time - получить время

ИСПОЛЬЗОВАНИЕ

      #include <sys/types.h>
      #include <time.h>

      time_t time(time *tloc);

ОПИСАНИЕ

      time возвращает  значение времени  в секундах  от 1 января 1970,
      00:00:00 UTC.  Если tloc  не равен  нулю, возвращаемое  значение
      будет также сохранено в переменной, на которую указывает tloc.

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

      При успешном завершении, time возвращает значение времени. Иначе
      возвращается значение  -1  и  значение  errno  отражает  причину
      ошибки.

СМ. ТАКЖЕ

      ctime(3C), stime(2).

                    Примеры использования time(2)

На следующей странице приведены примеры различных способов
использования системного вызова time.
.    описания и инициализации. Должны быть включены файлы,
перечисленные в Руководстве. Они объявляют  системный вызов time(2) и
описывают typedef time_t. Описаны четыре переменные типа time_t и
указатель на time_t. При этом указатель инициализируется.
.    нулевое значение параметра time(2) означает, что должно
использоваться возвращаемое значение. Под результат не было выделено
памяти, и предполагается использовать возвращаемое значение.
.    инициализированный указатель в качестве аргумента. Время будет
сохранено в объекте, на который указывает переменная tp. Поскольку tp
инициализирован, *tp совпадает с переменной t2. Кроме того, то же
самое значение будет присвоено t3.
.    адрес переменной в качестве аргумента. Прочитанное значение
системных часов будет помещено в переменную типа time_t.
Преобразование типа возвращаемого значения в void означает, что
возвращаемое значение не будет использоваться.
                    ПРИМЕРЫ ИСПОЛЬЗОВАНИЯ time(2)

.  объявления и инициализации

        #include <sys/types.h>
        #include <time.h>
        time_t t1, t2, t3, t4;
        time_t *tp = &t2;

.  нулевое значение параметра time(2) означает, что должно
   использоваться возвращаемое значение

        t1 = time ( 0 );

.  инициализированный указатель в качестве аргумента

        t3 = time ( tp );

.  адрес переменной в качестве аргумента

        (void) time ( &t4 );
                Пример страницы Руководства (Секция 3)

В разделе ИСПОЛЬЗОВАНИЕ описано несколько функций.
.    Должен быть включен файл <time.h>.
.    ctime, localtime и gmtime все требуют по одному параметру. Это
адрес объекта типа time_t, как правило, установленный ранее обращением
к time(2).
   -  ctime возвращает  адрес символа.  Это  адрес  начала  символьной
      строки, завершающийся нулевым символом.

   -  localtime и gmtime возвращают адрес структуры tm.

Раздел ОПИСАНИЕ описывает возвращаемое значение и элементы структуры
tm.
Замечания:
1. localtime  сначала   вызывает  tzset,   чтобы   получить   значение
   переменной  shell   TZ.   На   основании   этого   значения   tzset
   инициализирует  массив   указателей  на  строки  tzname  и  внешние
   переменные timezone  и  altzone.  timezone  устанавливается  равной
   разнице времени  между UTC  и данной временной зоной, измеренному в
   секундах. Например, в Нью Джерси,

   tzname[0] == "EST" и timezone == 5*60*60
   tzname[1] == "EDT" и altzone == 4*60*60

2. Поле tm_isdst  структуры tm  при вызове  функций localtime и gmtime
   устанавливается положительным,  если действует  сезонное  изменение
   времени, нулевым,  если оно  не действует,  и  отрицательным,  если
   информация недоступна.
3. Внешняя переменная  daylight устанавливается  положительной, только
   если в данной TZ используется сезонное изменение времени.
4. localtime реализована  следующим образом:  она вычитает timezone из
   прочитанного значения  time  и  вызывает  gmtime.  Раздел  ПРОБЛЕМЫ
   говорит  о   "перезаписи"  содержимого.   Информация,  на   которую
   указывает значение,  возвращенное localtime или gmtime, должна быть
   обработана, прежде чем любая из этих функций будет вызвана еще раз.

Замечание: если вы компилируете в режиме строгого ANSI C (опция
-Xc), файл <time.h> не будет включать описание extern для переменных
timezone, altzone, daylight и tzname. Вы должны либо компилировать с
ключом -Xa, либо явно добавить соответствующие описания в вашу
программу.
Библиотечная функция mktime(3C) может быть использована для
преобразования структуры tm в календарное время (количество секунд с
00:00:00 1 января 1970).
Библиотечная функция difftime(3C) возвращает разницу между двумя
календарными временами как double. Эта функция нужна, потому что для
типа time_t не определено основных арифметических операций.
                ПРИМЕР СТРАНИЦЫ РУКОВОДСТВА (СЕКЦИЯ 3)
CTIME(3C)               UNIX System V               CTIME(3C)



ИМЯ
      ctime, localtime, gmtime, asctime, tzset - преобразование даты и
      времени в строку

ИСПОЛЬЗОВАНИЕ
      #include <time.h>
      char * ctime(const time_t *clock);
      struct tm * localtime(const time_t *clock);
      struct tm * gmtime(const time_t *clock);
      char * asctime(const struct tm * tm);
      extern time_t timezone, altzone;
      extern int daylight;
      extern char *tzname[2];
      void tzset(void);

ОПИСАНИЕ
      ctime, localtime  и gmtime  получают аргумент  типа указатель на
      time_t, представляющий  время в секундах с 00:00:00 UTC 1 января
      1970. ctime  возвращает  указатель  на  строку  из  26  символов
      следующего вида ...

      Sun Sep 16 01:03:52 1973\n\0

      ... Объявление  всех  функций  и  внешних  переменных,  а  также
      описание структуры  tm, содержатся  в файле  <time.h>.  Описание
      структуры выглядит так:

      struct tm {
      int tm_sec;    /* seconds after minute [0,61] */
      int tm_min;    /* minutes after the hour [0,59] */
      int tm_hour;   /* hour since midnight [0,23] */
      int tm_mday;   /* day of the month [1,31] */
      int tm_mon;    /* months since January [0,11] */
      int tm_year;   /* years since 1900 */
      int tm_wday;   /* days since Sunday [0,6] */
      int tm_yday;   /* days since January 1 [0,365] */
      int tm_isdst;  /* flag for alternate daylight savings time */
      };


               Пример использования time(2) и ctime(3C)

Эта программа демонстрирует использование time(2) и ctime(3C). Она
работает следующим образом:
   9      Определяет переменную now типа time_t.

   10     Определяет указатель sp на struct tm.

   12     Вызывается time(2).  Время в  секундах  от  00:00:00  UTC  1
          января 1970 сохраняется в переменной now.

   14     Библиотечная функция ctime(3C) преобразует календарное время
          в ASCII-строку  формата date(1).   Адрес,  возвращенный этой
          функцией,  используется  в  качестве  параметра  printf  для
          печати ASCII-строки.

   16     Вызывается библиотечная  функция localtime(3C).  Эта функция
          заполняет значениями поля структуры tm.

   17-20  Распечатываются значения полей структуры tm.

Файл: ex_time.c
                         ПРИМЕР ИСПОЛЬЗОВАНИЯ
                          time(2) И ctime(2)
 1 #include <sys/types.h>
 2 #include <stdio.h>
 3 #include <time.h>
 4 #include <stdlib.h>
 5 extern char *tzname[];
 6
 7 main()
 8 {
 9     time_t now;
10     struct tm *sp;
11
12     (void) time( &now );
13
14     printf("%s", ctime( &now ) );
15
16     sp = localtime(&now);
17     printf("%d/%d/%02d %d:%02d %s\n",
18         sp->tm_mon + 1, sp->tm_mday,
19         sp->tm_year, sp->tm_hour,
20         sp->tm_min, tzname[sp->tm_isdst]);
21     exit(0);
22 }