strcoll(3c) [opensolaris man page]

strcoll(3C)						   Standard C Library Functions 					       strcoll(3C)

NAME

       strcoll - string collation

SYNOPSIS

       #include <string.h>

       int strcoll(const char *s1, const char *s2);

DESCRIPTION

       Both  strcoll()	and strxfrm(3C) provide for locale-specific string sorting.  strcoll() is intended for applications in which the number of
       comparisons per string is small. When strings are to be compared a number of times, strxfrm(3C) is a more appropriate function because  the
       transformation process occurs only once.

       The strcoll() function does not change the setting of errno if successful.

       Since  no  return  value is reserved to indicate an error, an application wishing to check for error situations should set errno to 0, then
       call strcoll(), then check errno.

RETURN VALUES

       Upon successful completion, strcoll() returns an integer greater than, equal to, or less than zero in direct correlation to whether  string
       s1  is  greater than, equal to, or less than the string s2.  The comparison is based on strings interpreted as appropriate to the program's
       locale  for category LC_COLLATE (see setlocale(3C)).

       On error, strcoll() may set errno, but no return value is reserved to indicate an error.

ERRORS

       The strcoll() function may fail if:

       EINVAL	 The s1 or s2 arguments contain characters outside the domain of the collating sequence.

FILES

       /usr/lib/locale/locale/locale.so.*

	   LC_COLLATE database for locale

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |CSI			     |Enabled			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe with exceptions	   |
       +-----------------------------+-----------------------------+

       The strcoll() function can be used safely in multithreaded applications, as long as setlocale(3C) is not being called to change the locale.

SEE ALSO

       localedef(1), setlocale(3C), string(3C), strxfrm(3C), wsxfrm(3C), attributes(5), environ(5), standards(5)

SunOS 5.11							    1 Nov 2003							       strcoll(3C)

STRCOLL(3P)						     POSIX Programmer's Manual						       STRCOLL(3P)

PROLOG

       This  manual page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (consult the correspond-
       ing Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.

NAME

       strcoll - string comparison using collating information

SYNOPSIS

       #include <string.h>

       int strcoll(const char *s1, const char *s2);

DESCRIPTION

       The strcoll() function shall compare the string pointed to by s1 to the string pointed to by s2, both interpreted  as  appropriate  to  the
       LC_COLLATE category of the current locale.

       The strcoll() function shall not change the setting of errno if successful.

       Since  no  return  value is reserved to indicate an error, an application wishing to check for error situations should set errno to 0, then
       call strcoll(), then check errno.

RETURN VALUE

       Upon successful completion, strcoll() shall return an integer greater than, equal to, or less than  0,  according  to  whether  the  string
       pointed	to  by s1 is greater than, equal to, or less than the string pointed to by s2 when both are interpreted as appropriate to the cur-
       rent locale.  On error, strcoll() may set errno, but no return value is reserved to indicate an error.

ERRORS

       The strcoll() function may fail if:

       EINVAL The s1 or s2 arguments contain characters outside the domain of the collating sequence.

       The following sections are informative.

EXAMPLES

   Comparing Nodes
       The following example uses an application-defined function, node_compare(), to compare two nodes based on an alphabetical ordering  of  the
       string field.

	      #include <string.h>
	      ...
	      struct node { /* These are stored in the table. */
		  char *string;
		  int length;
	      };
	      ...
	      int node_compare(const void *node1, const void *node2)
	      {
		  return strcoll(((const struct node *)node1)->string,
		      ((const struct node *)node2)->string);
	      }
	      ...

APPLICATION USAGE

       The strxfrm() and strcmp() functions should be used for sorting large lists.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       strcmp(), strxfrm(), the Base Definitions volume of IEEE Std 1003.1-2001, <string.h>

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Standard for Information Technol-
       ogy -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
       Electrical  and	Electronics  Engineers, Inc and The Open Group. In the event of any discrepancy between this version 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 .

IEEE
/The Open Group						       2003							       STRCOLL(3P)