.\"	$NetBSD: types.3,v 1.6 2011/04/10 10:02:34 jruoho Exp $
.\"
.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Jukka Ruohonen.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.\" Copyright (c) 1980, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)types.5	8.1 (Berkeley) 6/5/93
.\"
.Dd April 10, 2011
.Dt TYPES 3
.Os
.Sh NAME
.Nm types
.Nd standard system data types
.Sh SYNOPSIS
.In sys/types.h
.Sh DESCRIPTION
The
.In sys/types.h
header contains the common data types used in the system.
Although these are meant to be used within the kernel,
most of the system data types are accessible also to user code.
A companion header
.In sys/param.h ,
typically used in the kernel,
includes
.In sys/types.h
and provides additional types as well as other facilities (see
.Xr param 3 ) .
.Ss Standard Types
The following standards-compliant system data types are defined:
.Pp
.Bl -column -offset indent \
"suseconds_t " "process and process group IDs " "clock_settime(3) "
.It Sy Type Ta Sy Typical use Ta Sy Example
.It Va blkcnt_t Ta file block counts Ta Xr stat 2
.It Va blksize_t Ta block sizes Ta Xr stat 2
.It Va clock_t Ta system clock ticks Ta Xr clock 3
.It Va clockid_t Ta clock IDs Ta Xr clock_settime 2
.It Va dev_t Ta device IDs Ta Xr devname 3
.It Va fsblkcnt_t Ta file system block counts Ta -
.It Va fsfilcnt_t Ta file system file counts Ta -
.It Va gid_t Ta group IDs Ta Xr getgid 2
.It Va id_t Ta general identifier Ta Xr pset 3
.It Va ino_t Ta file serial numbers Ta Xr fs 5
.It Va key_t Ta interprocess communication Ta Xr ftok 3
.It Va mode_t Ta file attributes Ta Xr stat 2
.It Va nlink_t Ta link counts Ta Xr stat 2
.It Va off_t Ta file sizes Ta Xr fseek 3
.It Va pid_t Ta process and process group IDs Ta Xr getpid 2
.It Va size_t Ta size of objects Ta Xr stddef 3
.It Va ssize_t Ta count of bytes Ta Xr write 2
.It Va suseconds_t Ta microseconds Ta Xr gettimeofday 2
.It Va time_t Ta time in seconds Ta Xr time 3
.It Va timer_t Ta timer IDs Ta Xr timer_create 2
.\"
.\" XXX: Following are undefined in NetBSD at the time of writing:
.\"
.\".It Va trace_attr_t Ta trace stream attributes Ta -
.\".It Va trace_event_id_t Ta trace event type Ta -
.\".It Va trace_event_set_t Ta trace event type set Ta -
.\".It Va trace_id_t Ta trace stream ID Ta -
.It Va uid_t Ta user IDs Ta Xr setuid 2
.It Va useconds_t Ta time in microseconds Ta Xr usleep 3
.El
.Pp
In addition, when included in user applications,
.In sys/types.h
includes
.In pthread.h ,
and thus it defines also the types used in the
.Tn POSIX
Threads Library,
.Xr pthread 3 .
.Pp
Each described type may vary across machines and operating systems.
Only the following properties are guaranteed by the
.St -p1003.1-2001
standard:
.Bl -enum -offset indent
.It
The type
.Em ssize_t
is capable of storing integer values at least in the range [\-1,
.Dv SSIZE_MAX ] .
.It
The type
.Em useconds_t
is an unsigned integer capable of storing
values at least in the range [0, 1000000].
.It
The type
.Em suseconds_t
is a signed integer capable of storing
values at least in the range [\-1, 1000000].
.It
The
.Em time_t
and
.Em clock_t
types are either integers or real-floating types.
.It
The following types are integers:
.Em gid_t ,
.Em id_t ,
.Em mode_t ,
.Em nlink_t ,
and
.Em uid_t .
.It
The following types are signed integers:
.Em blkcnt_t ,
.Em blksize_t ,
.Em off_t ,
.Em pid_t ,
and
.Em ssize_t .
.It
The following types are unsigned integers:
.Em fsblkcnt_t ,
.Em fsfilcnt_t ,
.Em ino_t ,
and
.Em size_t .
.El
.Ss NetBSD-specific Types
In addition to the standard types,
.In sys/types.h
defines some data types specific to
.Nx .
These are mostly used in the kernel.
A portable implementation should not rely
on these types to be available in other systems.
Examples include:
.Bl -column -offset indent \
"suseconds_t " "synonym for uint64_t   " "getdevmajor(3) "
.It Sy Type Ta Sy Typical use Ta Sy Example
.It Va cpuid_t Ta CPU IDs Ta Xr cpuset 3
.It Va daddr_t Ta disk address Ta Xr buffercache 9
.It Va devmajor_t Ta major device number Ta Xr getdevmajor 3
.It Va lwp_t Ta typedef of Va struct lwp Ta Xr kthread 9
.It Va u_quad_t Ta synonym for Va uint64_t Ta Xr strtouq 3
.El
.Pp
It can be noted that the standard
.Dq C99 types
described in
.Xr stdint 3
are preferred to the older fixed size integer types prefixed with an
.Dq u_
(in other words,
.Va uint32_t
should be used instead of
.Va u_int32_t ) .
.Sh SEE ALSO
.Xr param 3 ,
.Xr stdbool 3 ,
.Xr stddef 3 ,
.Xr stdint 3 ,
.Xr stdlib 3 ,
.Xr unistd 3
.Sh STANDARDS
The
.In sys/types.h
header conforms to
.St -p1003.1-2001
with respect to the described standard types.
.Sh HISTORY
The
.In sys/types.h
header first appeared in
.At v7 .
In the current form the header appeared in
.Nx 0.9 .